Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

Pipeline Design 3

Seth Ford edited this page Feb 8, 2026 · 2 revisions

Design: Add daemon quick-start section to README

Context

The Shipwright README (README.md) documents the autonomous daemon feature but lacks a quick-start guide for new users. The current "Autonomous Daemon" section (approximately lines 363-405) covers the concept but doesn't provide actionable steps to get running quickly. Users need to piece together information from multiple sections to start the daemon, configure it, and monitor it.

This is a documentation-only change — no code is modified. The primary constraint is preserving all existing content and maintaining consistency with the README's existing style (markdown tables, fenced code blocks, command examples with shipwright CLI).

Decision

Restructure the existing "Autonomous Daemon" section in README.md into four focused subsections:

  1. Quick Start — A numbered 5-step guide covering: generate config (shipwright daemon init), edit config, start daemon (shipwright daemon start), start detached (--detach), and check status (shipwright daemon metrics).

  2. Configuration — A markdown table of key daemon config fields (max_parallel, auto_scale, max_workers, min_workers, poll_interval, self_optimize, auto_template, max_retries, priority_lane) with types, defaults, and descriptions. Reference the existing CLAUDE.md config table for consistency.

  3. Monitoring — Three essential monitoring commands: shipwright daemon metrics (DORA dashboard), shipwright status (team dashboard), and shipwright logs <team> --follow (tail logs).

  4. Auto-Scaling — Explanation of dynamic worker scaling with the four scaling factors (CPU, memory, budget, queue demand), plus a JSON config snippet showing the relevant fields.

This approach follows the existing README pattern of using ### subsections under ## feature sections, markdown tables for configuration, and fenced code blocks for examples.

Alternatives Considered

  1. Separate daemon documentation file — Pros: Keeps README concise, allows deeper coverage / Cons: Fragments documentation, users must navigate to a second file for basic setup, inconsistent with how other features (fleet, pipeline) are documented in the README.

  2. Add quick-start to top-level "Quick Start" section only — Pros: Users find it immediately / Cons: Separates daemon quick-start from daemon reference content, creates duplication if daemon details remain in their own section.

  3. Minimal inline edits (just add a "getting started" paragraph) — Pros: Smallest diff / Cons: Doesn't address the structural gap — users still lack a config reference table and monitoring commands in context.

Implementation Plan

  • Files to create: None
  • Files to modify: README.md — replace the Autonomous Daemon section (~lines 363-405) with the expanded 4-subsection version
  • Dependencies: None
  • Risk areas:
    • Line numbers may have shifted if other PRs merged — locate the section by heading text (## Autonomous Daemon) rather than line numbers
    • Ensure the config field names and defaults match the actual code in scripts/cct-daemon.sh and the daemon config JSON schema
    • Verify command examples (shipwright daemon init, shipwright daemon start --detach, shipwright daemon metrics) match current CLI behavior

Validation Criteria

  • The ## Autonomous Daemon section contains four subsections: Quick Start, Configuration, Monitoring, Auto-Scaling
  • Quick Start has exactly 5 numbered steps with valid shipwright commands
  • Configuration table fields match those in .claude/CLAUDE.md daemon configuration table and scripts/cct-daemon.sh
  • All three monitoring commands are documented and match actual CLI subcommands
  • Auto-Scaling section includes the JSON config snippet with auto_scale, auto_scale_interval, max_workers, min_workers, worker_mem_gb, and estimated_cost_per_job_usd
  • No existing content outside the Autonomous Daemon section is modified
  • Markdown renders correctly (tables, code blocks, headings)
  • npm test passes (no test regressions from doc-only change)

Clone this wiki locally

AltStyle によって変換されたページ (->オリジナル) /