feature-flow-cli 0.1.0__py3-none-any.whl

feature_flow/_bundle/skills/architect-review/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: architect-review
+description: Enterprise architecture review — evaluate a module, feature, or PR diff against production-grade standards. Covers resilience, observability, data contracts, scalability, and security. Returns a prioritized findings report with severity ratings.
+argument-hint: "[file-path | feature-name | 'staged' | 'last-commit']"
+---
+
+Perform an enterprise-grade architecture review of `$ARGUMENTS`.
+
+## Step 0: Gather the target
+
+- If `$ARGUMENTS` is `staged` → run `git diff --staged`
+- If `$ARGUMENTS` is `last-commit` → run `git diff HEAD~1 HEAD`
+- If `$ARGUMENTS` is a file path → read the file
+- If `$ARGUMENTS` is a feature name → search `plans/$ARGUMENTS/` (or the project's ticket folder) and the relevant source directories
+- If `$ARGUMENTS` is empty → review `git diff --staged`
+
+Read all relevant files before forming any judgements. For backend code, also read the module file and any dependent service interfaces.
+
+---
+
+## Step 1: Structural Architecture Review
+
+### Module Boundaries
+- [ ] **Single Responsibility**: Does each class/module own exactly one domain concern?
+- [ ] **Interface Segregation**: Are interfaces narrow (consumers depend only on what they use)?
+- [ ] **Dependency Direction**: Do dependencies flow inward (domain ← application ← infrastructure)?
+- [ ] **Circular Dependencies**: Any imports that cycle back to the same module?
+- [ ] **Module Encapsulation**: Is the public surface (exports, registered providers) deliberate, with internals kept private?
+
+### Data Contracts
+- [ ] **Typed boundaries**: All external inputs (WS messages, HTTP bodies, API responses) validated with typed guards?
+- [ ] **Discriminated unions**: Event/message types use union types, not string comparisons?
+- [ ] **No `any`**: Every `any` is a contract hole — flag each one with its severity
+- [ ] **Shared types**: Cross-boundary types live in one shared definition, not duplicated per side?
+- [ ] **Immutability**: Config objects and props marked `readonly`?
+
+---
+
+## Step 2: Resilience & Fault Tolerance Review
+
+For each async operation or external call found in the code:
+
+- [ ] **Timeout**: Is there a timeout guard? Unbounded awaits are production incidents.
+- [ ] **Retry**: Is retry implemented with exponential backoff + jitter for transient failures?
+- [ ] **Circuit Breaker**: Is there a circuit breaker to stop cascading failure under sustained errors?
+- [ ] **Idempotency**: Can this operation safely run twice without side effects?
+- [ ] **Dead Letter / Fallback**: What happens when the operation permanently fails?
+- [ ] **Graceful Degradation**: Does the system continue operating (degraded) when this service is unavailable?
+- [ ] **Bulkhead Isolation**: Can failure in this path impact unrelated request paths?
+
+---
+
+## Step 3: Observability Review
+
+- [ ] **Structured logging**: All log calls use the project's structured logger with metadata, no bare `console.log` / `print`
+- [ ] **Correlation IDs**: Are request/session IDs propagated through async boundaries?
+- [ ] **Error context**: Caught errors logged with `{ error, stack, context }` — not just `err.message`
+- [ ] **Operation timing**: Are slow paths (AI calls, DB queries, external APIs) measured?
+- [ ] **Failure visibility**: Are error conditions logged at `error` level, warnings at `warn`?
+- [ ] **OpenTelemetry**: Are spans created for significant operations? Is trace context propagated?
+
+---
+
+## Step 4: Performance & Scalability Review
+
+- [ ] **Blocking operations**: Any sync-heavy work on the event loop that should be offloaded?
+- [ ] **N+1 queries**: Any DB or cache access inside a loop?
+- [ ] **Caching opportunity**: Is expensive, repeated computation cached (Redis or in-memory with TTL)?
+- [ ] **Queue offload**: Should long-running work be pushed to a background job queue instead of awaited inline?
+- [ ] **Memory leaks**: Event listeners, intervals, and subscriptions cleaned up properly?
+- [ ] **Pagination**: Are unbounded list queries guarded with limits?
+
+---
+
+## Step 5: Security Review
+
+- [ ] **Input validation**: All external inputs sanitized before use?
+- [ ] **Injection risk**: Any user data concatenated into queries, shell commands, or log messages?
+- [ ] **Auth guards**: Are protected routes/WS handlers gated with auth checks?
+- [ ] **Secret exposure**: No secrets, API keys, or PII in logs or error responses?
+- [ ] **Human-in-the-loop**: Destructive or irreversible operations require explicit user approval?
+- [ ] **Rate limiting**: Are high-frequency endpoints or WS message types rate-limited?
+
+---
+
+## Step 6: Testability Review
+
+- [ ] **Dependency injection**: Are dependencies injected (not instantiated inline) so they can be mocked?
+- [ ] **Pure functions**: Are complex transformations extracted as pure, easily-testable functions?
+- [ ] **Test surface**: Is there a test in the project's test directory covering the primary paths?
+- [ ] **Edge cases in tests**: Are error paths (timeout, null input, unavailable service) tested?
+
+---
+
+## Step 7: Project Convention Violations
+
+Read `CLAUDE.md`, `AGENTS.md`, and any contributing or style docs in the repo. For each explicit rule or "forbidden" item they list, check whether the target violates it, and add each violation to the findings table with the rule it breaks. If the repo documents no conventions, mark this category ✅ PASS.
+
+---
+
+## Step 8: Produce the Report
+
+Output a prioritized findings report:
+
+```
+## Architecture Review: [target]
+
+### Summary
+[1-3 sentence overall assessment: is this production-ready, needs hardening, or has blockers?]
+
+### Severity Legend
+🔴 BLOCKER — Must fix before merge. Production incident risk or contract breakage.
+🟠 HIGH    — Fix in this PR or immediately after. Degrades reliability or observability.
+🟡 MEDIUM  — Fix in next iteration. Code smell or missing best practice.
+🟢 LOW     — Nice to have. Minor improvement.
+✅ PASS    — No issues found in this category.
+
+---
+
+### Findings
+
+| # | Severity | Category | Location | Issue | Recommendation |
+|---|----------|----------|----------|-------|----------------|
+| 1 | 🔴 | Resilience | `ServiceName.method()` | No timeout on upstream API call | Wrap with `Promise.race([call, timeout(10_000)])` |
+| 2 | 🟠 | Observability | `handler.ts:42` | Error caught but not logged with context | `logger.error('Failed to process', { error: e.message, sessionId })` |
+...
+
+---
+
+### Categories with No Issues
+✅ Data Contracts — all types narrow and properly guarded
+✅ Security — inputs validated, auth guards present
+...
+
+---
+
+### Recommended Next Actions
+1. [Highest priority fix — one sentence]
+2. [Second priority fix]
+3. [Optional improvement]
+```
+
+If there are zero findings in a category, mark it ✅ PASS — do not pad the report with empty sections.

feature_flow/_bundle/skills/automation-design/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: automation-design
+description: Design an enterprise-grade automation pipeline or workflow system. Takes a plain-language description of what needs to be automated and produces a full technical blueprint: pipeline stages, fault-tolerance model, state machine, data contracts, observability plan, and a phased implementation plan that the feature-flow skill can turn into tickets.
+argument-hint: "[plain-language description of the automation, e.g., 'auto-retry failed jobs with backoff', 'nightly batch import pipeline', 'resume interrupted uploads']"
+---
+
+Design an enterprise automation system for: **$ARGUMENTS**
+
+You are a world-class automation architect. You design systems that are **reliable at scale**, **observable in production**, and **maintainable by a team**. Every automation you design has a clear failure model, not just a happy path.
+
+---
+
+## Step 1: Clarify the Automation Scope
+
+Before designing, establish:
+
+1. **Trigger**: What starts the automation? (user action, schedule, event, webhook, threshold breach)
+2. **Input**: What data does it receive? What is the expected shape and validation requirements?
+3. **Output / Side Effect**: What does it produce or change? (DB write, API call, UI update, message sent)
+4. **Frequency & Volume**: How often? How many concurrent instances? What's the peak load?
+5. **Latency Requirement**: Is this real-time (<100ms), near-real-time (<2s), or batch (minutes)?
+6. **Failure Tolerance**: What's acceptable? (retry silently, alert user, block, compensate?)
+7. **Statefulness**: Does it need to resume after interruption, or restart from scratch?
+
+If the user already provided enough context, skip the interview and proceed to Step 2.
+
+---
+
+## Step 2: Research Existing Patterns
+
+Before proposing anything new, read the codebase:
+
+1. **Existing pipeline code** — workers, job processors, schedulers, event handlers
+2. **Existing workflow patterns** — similar automations already in the repo, and existing `plans/` folders
+3. **Shared types** — existing message/event/contract types the automation should reuse
+4. **Job queue usage** — how existing jobs are defined, retried, and monitored
+5. **Trigger and message flow** — existing gateways, controllers, or event buses the automation could plug into
+
+Identify: what can be reused, what needs extending, what must be built from scratch.
+
+---
+
+## Step 3: Design the Automation Blueprint
+
+### 3a. Pipeline Stage Diagram
+
+Model the automation as a sequence of named, isolated stages:
+
+```
+[Trigger / Input]
+      │
+      ▼
+┌─────────────────────────────────────────────┐
+│  Stage 1: INPUT VALIDATION                  │
+│  • Validate schema (throw on invalid)        │
+│  • Normalize / enrich input                  │
+│  • Emit: validation.passed / failed metric   │
+└─────────────────────────────────────────────┘
+      │ valid input
+      ▼
+┌─────────────────────────────────────────────┐
+│  Stage 2: [DOMAIN PROCESSING STAGE NAME]    │
+│  • [Core business logic]                     │
+│  • Side effect: [DB write / API call / etc.] │
+│  • Retry: [yes/no — strategy]               │
+└─────────────────────────────────────────────┘
+      │
+      ├─── success ──► [Stage 3 or Output]
+      │
+      └─── failure ──► [Error Handler / DLQ]
+```
+
+Rules for pipeline design:
+- Each stage is a **single responsibility** — one input, one output, one error path
+- Stages communicate via **typed events or return values**, never shared mutable state
+- Each stage logs entry, exit, and duration
+- Each stage that calls an external system has a **timeout + fallback**
+
+### 3b. State Machine (if stateful)
+
+If the automation has multiple states (e.g., a multi-step workflow), define the state machine:
+
+```
+States:     PENDING → RUNNING → [COMPLETED | FAILED | RETRYING | CANCELLED]
+
+Transitions:
+  PENDING   + trigger      → RUNNING     (persist state, start processing)
+  RUNNING   + success      → COMPLETED   (persist result, emit event)
+  RUNNING   + retryable    → RETRYING    (increment attempt, schedule next)
+  RUNNING   + fatal-error  → FAILED      (persist error, alert, DLQ)
+  RETRYING  + max-attempts → FAILED
+  *         + cancel       → CANCELLED   (compensate if needed)
+```
+
+### 3c. Fault Tolerance Model
+
+For each external call or async operation in the pipeline:
+
+| Operation | Timeout | Retry Strategy | Max Attempts | Circuit Breaker | Fallback |
+|-----------|---------|----------------|--------------|-----------------|---------|
+| [op name] | [ms] | [exp backoff + jitter] | [N] | [yes/no] | [what happens] |
+
+**Retry formula**: `delay = min(baseDelay * 2^attempt + jitter(0..500ms), maxDelay)`
+
+### 3d. Data Contracts
+
+Define all types at the pipeline boundary:
+
+```typescript
+// Input contract
+interface AutomationInput {
+  readonly id: string;           // correlation ID for tracing
+  readonly triggeredBy: string;  // user ID or system
+  readonly payload: [specific type];
+  readonly metadata: {
+    readonly sessionId: string;
+    readonly timestamp: number;
+  };
+}
+
+// Output / result contract
+type AutomationResult =
+  | { readonly status: 'completed'; readonly output: [type]; readonly duration: number }
+  | { readonly status: 'failed';    readonly error: string;  readonly attempt: number }
+  | { readonly status: 'partial';   readonly completed: [type][]; readonly failed: [type][] };
+
+// Event emitted to consumers
+interface AutomationEvent {
+  readonly type: 'automation.completed' | 'automation.failed' | 'automation.step';
+  readonly automationId: string;
+  readonly payload: AutomationResult;
+}
+```
+
+### 3e. Observability Plan
+
+Every automation must be observable. Define:
+
+```
+Logs (structured):
+  INFO  — stage start/end with duration
+  WARN  — retryable failure (attempt N of M)
+  ERROR — fatal failure with full context { error, stack, input.id, stage }
+
+Metrics (OpenTelemetry or the project's metrics library):
+  automation.[name].duration     — histogram
+  automation.[name].success      — counter
+  automation.[name].failure      — counter (tagged by stage + error type)
+  automation.[name].retry        — counter
+  automation.[name].queue.depth  — gauge (if queue-based)
+
+Traces:
+  Root span: automation.[name]
+  Child spans: one per stage
+  Attributes: correlation ID, input size, output size, attempt count
+```
+
+### 3f. Job Queue Configuration (if async/background)
+
+Express these settings in whatever queue library the project already uses:
+
+```typescript
+// Job definition
+interface [AutomationName]Job {
+  data: AutomationInput;
+  opts: {
+    attempts: 3,
+    backoff: { type: 'exponential', delay: 1000 },
+    removeOnComplete: 100,  // keep last 100 completed
+    removeOnFail: 500,      // keep last 500 failed for debugging
+    timeout: 30_000,        // kill job after 30s
+  };
+}
+```
+
+---
+
+## Step 4: Integration Points
+
+Map how this automation fits into the project's existing architecture:
+
+```
+[Where it plugs in]
+  ├── Message trigger → existing gateway/handler → new message type: [name]
+  ├── OR HTTP trigger → new endpoint on an existing service
+  ├── OR Scheduled → queue or scheduler cron job
+  └── OR Event-driven → subscribes to existing [EventName] event
+
+[Output goes to]
+  ├── Stream back to the client (real-time progress)
+  ├── OR DB persistence (entity/table: [name])
+  ├── OR Cache (TTL: [value])
+  └── OR triggers downstream automation: [name]
+```
+
+---
+
+## Step 5: Implementation Plan
+
+Produce a phased plan. Each phase should be small enough to become one ticket:
+
+### Phase 1: Types & Contracts
+- Define all input/output/event types where the project keeps shared types
+- No implementation — types only
+- Verify: `[the project's build or typecheck command]`
+
+### Phase 2: Core Pipeline Service
+- Create the service in the project's usual location for the domain, named after the automation
+- Implement pipeline stages as private methods
+- Inject dependencies (optional services gracefully degrade)
+- Include full fault tolerance (retry, timeout, circuit breaker)
+- Verify: `[the project's build command]`
+
+### Phase 3: Queue / Trigger Integration
+- Register the queue processor if async
+- Wire into the chosen trigger: gateway, endpoint, scheduler or event subscription
+- Add routing for the new message type or route
+- Verify: `[the project's build command]`
+
+### Phase 4: Tests
+- Unit tests for each pipeline stage in isolation
+- Integration test for the happy path
+- Error path tests (timeout, retry exhaustion, invalid input)
+- Verify: `[the project's test command]`
+
+### Phase 5: Client / UI Integration (only if the automation has a user-facing surface)
+- Add client state for tracking automation status
+- Wire event listeners for progress streaming
+- UI: progress indicator + error state
+- Verify: `[the client build and test command]`
+
+---
+
+## Step 6: Create Strategy Folder
+
+Ask the user: "Should I turn this design into a plan at `plans/[automation-name]/` (a spec, a map and a graph of tickets)?"
+
+If yes → plan it with the feature-flow skill (`/feature-flow [automation-name]` in Claude Code, `$feature-flow [automation-name]` in Codex), using this blueprint as the specification.
+
+---
+
+## Step 7: Output the Blueprint
+
+```
+## Automation Blueprint: [Name]
+
+### What it does
+[2-3 sentences: trigger → processing → output]
+
+### Architecture Pattern
+[Pipeline / State Machine / Event-Driven / Scheduled Batch]
+
+### Pipeline Stages
+[diagram from Step 3a]
+
+### Fault Tolerance Summary
+[table from Step 3c]
+
+### Key Data Types
+[contracts from Step 3d]
+
+### Integration Point
+[where it plugs in to the existing architecture]
+
+### Implementation Phases
+[phases from Step 5 — with file paths and verify commands]
+
+### Risks & Mitigations
+- [Risk 1]: [Mitigation]
+- [Risk 2]: [Mitigation]
+
+### Open Questions
+- [Any decisions that need user input before implementation]
+```

feature_flow/_bundle/skills/feature-flow/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: feature-flow
+description: Use to plan a feature or build its tickets, one fresh builder and one fresh reviewer subagent per ticket, with scripts/flow.py deciding every step. Also draws the ticket graph with show.
+argument-hint: "[feature] [show] [auto]"
+disable-model-invocation: true
+---
+
+Plan or build the feature in `$ARGUMENTS`.
+
+The first word is the **feature**. `show` means draw the graph. `auto` means ask nothing and go. If no feature was given, list `plans/*/` and ask which one.
+
+The conductor is `python3 scripts/flow.py <feature> <command>`. It decides the order, runs the gate and the floor guard, and keeps its state in `.feature-flow/state/`, a folder git ignores. You ask it, and you do what it says. The guides it uses are in `guides/` or `.feature-flow/guides/`.
+
+## Show
+
+With `show`, follow `guides/show.md` for the feature and stop.
+
+## Plan
+
+If `plans/<feature>/` does not exist, run `FLOW_INVOKE=/feature-flow python3 scripts/flow.py <feature> start` and check that it prints `PLAN`. Then:
+
+1. Follow `guides/plan.md` with the user.
+2. Run `python3 scripts/flow-status.py <feature> --check` and fix every problem.
+3. Stop. List the files you created and suggest the commit command (`git add plans/<feature> && git commit -m "docs(<feature>): plan"`). Say to commit the plan and run `/feature-flow <feature>` again. While the plan is uncommitted, do not say the feature is ready to build.
+
+## Before building
+
+With a plan present, check these before `start`, and stop at the first that fails:
+
+- `git status --porcelain` is empty.
+- `python3 scripts/flow-status.py <feature> --check` prints `OK`.
+- `ticket-builder.md` and `ticket-reviewer.md` are in `.claude/agents/`, `~/.claude/agents/`, or `$CLAUDE_HOME/agents/` when `CLAUDE_HOME` is set. If not, say to run `bash install.sh` from feature-flow.
+
+Then run `FLOW_INVOKE=/feature-flow python3 scripts/flow.py <feature> start`. It prints `OK <token>`. Keep the token and put `FLOW_SESSION=<token>` in front of **every** later conductor command, with `FLOW_INVOKE=/feature-flow`.
+
+If `start` prints `STOP` naming another owner, another session may still be working this feature. Ask the user whether that session is closed. Only on a clear yes, run `start` once more with `FLOW_TAKEOVER=1`. In `auto` mode, never take over: report and stop.
+
+Say what will happen: for each ticket, a builder subagent and then a reviewer subagent. After every few tickets (`FLOW_TICKETS_PER_SESSION`, default 4) you hand off to a new session. Ask for a yes, unless `auto` was given.
+
+## The loop
+
+Run `next`, act on its one line, and repeat:
+
+- `BUILD <ticket> <NN> <sha>`: run `prompt`. Spawn a `ticket-builder` subagent with that output as its whole prompt, and ask for a short summary back. Wait for its final reply: an Agent call can return before the subagent finishes, and the reply then arrives as a notification. Then run `next`.
+- `REVIEW <ticket> <NN> <sha>`: run `prompt` and spawn a `ticket-reviewer` subagent with it. Wait for its final reply. Save the whole reply with Bash, not the Write tool, into the conductor's git-ignored state folder: `cat > .feature-flow/state/flow-review-<feature>.txt <<'EOF'` ... `EOF`. Never under `.git`: an unattended session is refused there as a sensitive file. Then, as separate commands, run `verdict .feature-flow/state/flow-review-<feature>.txt` and `next`. If `verdict` prints `RETRY`, just run `next`.
+- `DONE <summary>`: report it and suggest `/feature-flow <feature> show`.
+- `STOP <reason>`: report the reason, run `python3 scripts/flow-status.py <feature>`, show the table, and stop.
+- `HANDOFF <line>`: stop here. Tell the user to open a new session and type exactly `<line>`. The new session resumes where this one stopped.
+
+A conductor command looks like this:
+
+    FLOW_SESSION=<token> FLOW_INVOKE=/feature-flow python3 scripts/flow.py <feature> next
+
+## Rules while building
+
+These apply from `start` on, once a plan exists. Planning (above) writes the plan files itself.
+
+- Never run the gate, the floor guard or a review yourself. The conductor runs the checks, and the reviewer subagent reviews.
+- Never edit a ticket, the plan or the code, and never commit. The builder does that.
+- Never skip a step, reorder steps, or decide the next step yourself. Only `next` decides.
+- Never read a ticket's `## Answer` into the reviewer's prompt. `prompt` already holds everything it needs.
+- Tell the user one short line per phase (`01 built`, `01 review: PASS`), not the subagents' reports.

feature_flow/checks.py

@@ -0,0 +1,71 @@
+"""The checks the conductor runs: the bash scripts it still calls, and the ported ones in process.
+
+Each call lives in one function so plans/interactive-flow-python can swap it for an
+in-process call without touching the conductor.
+"""
+
+import subprocess
+from pathlib import Path
+
+from feature_flow import status
+from feature_flow import gate as gate_module
+from feature_flow import floorguard
+
+
+class Result:
+    def __init__(self, code, out):
+        self.code = code
+        self.out = out
+
+    @property
+    def ok(self):
+        return self.code == 0
+
+
+class _Collect:
+    """stdout and stderr of an in-process port, folded together in the order they were written."""
+
+    def __init__(self):
+        self.parts = []
+
+    def write(self, text):
+        self.parts.append(text)
+
+    def text(self):
+        return "".join(self.parts)
+
+
+def _bash(script, *args):
+    result = subprocess.run(["bash", str(script)] + [str(a) for a in args],
+                            stdout=subprocess.PIPE, stderr=subprocess.STDOUT, universal_newlines=True)
+    return Result(result.returncode, result.stdout)
+
+
+def flow_status(scripts, feature, mode):
+    """The ticket graph reader with --next, --counts or --check, in process. stderr is folded into the output."""
+    out = _Collect()
+    code = status.run([feature, mode], out, out)
+    return Result(code, out.text())
+
+
+def gate(scripts, feature):
+    """The gate, run in process. stderr is folded into the output as the subprocess call did."""
+    chunks = []
+    code = gate_module.run(str(feature), chunks.append, chunks.append)
+    out = b"".join(chunks).decode("utf-8", "replace").replace("\r\n", "\n").replace("\r", "\n")
+    return Result(code, out)
+
+
+def floor_guard(scripts, feature, num, base):
+    """feature_flow.floorguard in-process; stdout and stderr are folded together in order."""
+    chunks = []
+    code = floorguard.run([str(feature), str(num), str(base)], chunks.append, chunks.append)
+    out = "".join(chunks).encode("utf-8", "surrogateescape").decode("utf-8", "replace")
+    return Result(code, out)
+
+
+def smoke(command):
+    args, use_shell = gate_module.shell(command)
+    result = subprocess.run(args, shell=use_shell, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                            universal_newlines=True)
+    return Result(result.returncode, result.stdout)

feature_flow/cli.py

@@ -0,0 +1,47 @@
+"""python3 scripts/flow.py <feature> <command>: the conductor's command line."""
+
+import sys
+from pathlib import Path
+
+from feature_flow.conductor import Conductor, NoPhase, Stop
+
+USAGE = "usage: python3 scripts/flow.py <feature> start | next | prompt | verdict <file>"
+COMMANDS = ("start", "next", "prompt", "verdict")
+
+
+def main(argv=None, scripts=None):
+    args = list(sys.argv[1:] if argv is None else argv)
+    if len(args) < 2 or args[1] not in COMMANDS or not args[0] or args[0].startswith("-"):
+        print(USAGE, file=sys.stderr)
+        return 2
+    feature, command = args[0], args[1]
+    if (command == "verdict") != (len(args) == 3) or len(args) > 3:
+        print(USAGE, file=sys.stderr)
+        return 2
+    scripts = Path(scripts) if scripts else Path.cwd() / "scripts"
+    conductor = None
+    try:
+        conductor = Conductor(feature, scripts)
+        if command == "verdict":
+            line = conductor.verdict(args[2])
+        elif command == "prompt":
+            line = conductor.prompt()
+        elif command == "start":
+            line = conductor.start()
+        else:
+            line = conductor.next()
+    except NoPhase as err:
+        print(err, file=sys.stderr)
+        return 2
+    except Stop as stop:
+        line = "STOP %s" % stop
+        if conductor is not None:
+            conductor.log("STOP")
+        print(line)
+        return 1
+    print(line, end="" if line.endswith("\n") else "\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

feature_flow/command.py

@@ -0,0 +1,39 @@
+"""feature-flow: the command an installed package puts on PATH (`uvx feature-flow-cli install .`).
+
+It installs the flow into a repo and reads a plan. The flow itself runs from the repo, as
+python3 scripts/flow.py, with the copy the installer put there.
+"""
+
+import os
+import sys
+
+from feature_flow import __version__, install, status, view
+
+USAGE = """\
+usage: feature-flow install [target-repo] [--agent claude|codex|all] [--user] [--force] [--dry-run]
+       feature-flow status <feature> [--next | --counts | --check | --mermaid [plain] | --json]
+       feature-flow view <feature> [--watch] [--no-open] [--out FILE]
+       feature-flow --version
+install copies the skill, its roles, scripts and guides into a repo; feature-flow install --help says more.
+status and view read plans/<feature>/ in the current directory, like scripts/flow-status.py and scripts/flow-view.py.
+"""
+
+
+def main(argv=None):
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args or args[0] in ("-h", "--help", "help"):
+        out = sys.stdout if args else sys.stderr
+        out.write(USAGE)
+        return 0 if args else 2
+    command, rest = args[0], args[1:]
+    if command in ("-V", "--version"):
+        print("feature-flow " + __version__)
+        return 0
+    if command == "install":
+        return install.main(install.source_root(), rest)
+    if command == "status":
+        return status.main(rest)
+    if command == "view":
+        return view.main(rest, here=os.path.join(install.source_root(), "scripts"))
+    sys.stderr.write("unknown command: %s\n%s" % (command, USAGE))
+    return 2