KC Dev Flow

Load development constraints in proportion to work risk, so agent behavior is just sufficient without losing verification or authority boundaries.

KC Dev Flow supplies one minimal authority core and three profile-native delivery routes. A repository may bind a planning provider, while its workflow runtime and delivery provider remain local. The design rationale records the observed pain, trade-offs, directional evidence, and conditions that would falsify this direction.

Routes

flowchart TB
    A["Backlog<br/>admit a Development Brief<br/>or Exploration Brief"] --> B["Captain selects a profile<br/>commit the work-item receipt"]
    B --> L["At each working stage, load<br/>shared core + selected base + selected stage"]
    L --> C{Selected profile}

    C -->|POC| P1["Build<br/>smallest real journey"]
    P1 --> P0{Direct proof?}
    P0 -->|yes| P4["Durable outcome<br/>terminal gate"]
    P0 -->|no| P2["RoboRev exit observation<br/>High+ · Spacedock adopters"]
    P2 --> P3["Fresh proof<br/>journey + riskiest assumption"]
    P3 --> D[Done]
    P4 --> D

    C -->|Pilot| T1["Shape<br/>bounded user journey"]
    T1 --> T2["Build<br/>real seams + recovery"]
    T2 --> T3["RoboRev exit observation<br/>Medium+ · Spacedock adopters"]
    T3 --> T4["Verify and deliver<br/>journey + data safety"]
    T4 --> D

    C -->|Production| R1["Shape<br/>operational boundaries"]
    C -->|Eligible Production recovery| R2
    R1 --> R2["Build<br/>operable lifecycle"]
    R2 --> R3["Risk-triggered RoboRev exit observation<br/>medium · Medium+ · Spacedock adopters"]
    R3 --> R4["Verify<br/>exact-revision obligations + rollout/rollback + release authority"]
    R4 --> D

An item leaves backlog only after its required brief is admitted. Scheduling metadata is optional; it activates provider reconciliation when present.

Backlog and done are state boundaries, not working stages; a runtime may expose the union of route states and skip inactive ones. The profile loader rejects a stage outside the committed route, so POC does not pay for Production policy merely because both ship in the package. The receipt belongs to the work item rather than the repository: one project can run POC, Pilot, and Production items concurrently, and each loader result hash-binds the exact item that selected its route.

Recovery is an explicit v3 Production receipt for one known failure. Its four fields make the ideation skip fail closed; changed premises require Captain fallback to the full route, while [none] does not activate RoboRev.

Each stage contract names a one-line working perspective — a cognitive cue, not another agent, review, or gate.

Inputs

• Development Brief — required for Pilot and Production; contains the problem, accepted outcome, complete non-goal list, route-back conditions, and one canonical ## Acceptance criteria section with concrete, unique, ascending AC-N bullets for new admission. Already-admitted prose is not migrated or rewritten.
• Exploration Brief — required for POC; uses the existing v3 decision, falsifier, budget, and stop-condition fields. New admissions also record an artifact class, safety boundary, and positive decision-ready minute limit; 15 is the default and a different limit requires its reason. A disposable POC adds a tentative architecture outline: components, data flow, external boundaries and assumptions. POC need not create docs/architecture.md; retained POC work still needs a proportional linked explanation. Pilot/Production requires that useful overview even with existing architecture docs, which it links for depth. Every continuation/worker reads the map before exploration; a missing non-POC map is bootstrapped before feature work. See Architecture home. The Captain-approved committed brief is the sole planning authority. source is free-text provenance and may hold a Linear URL or any other reference; KC Dev Flow never reads it as planning evidence, invokes no planning provider, and invents no Cycle or Release/Milestone. Feature and bug labels use the same engine; uncertainty, risk, urgency, and the accepted commitment select the brief and profile.

Seats and gates

• Captain owns scope, profile, irreversible actions, spend/permission, red residuals, and merge/release authorization.
• First Officer resolves authority, loads and dispatches the selected route, and applies declared gates.
• Chief Engineer gives bounded normal-delivery advice about the next smallest integrated step. It is not a mandatory reviewer.
• Science Officer gives independent assurance on a contested, high-risk, hard-to-reverse, or low-confidence technical claim. It is advisory. Both seats are trigger-based and stay unloaded on ordinary green transitions.
• Deterministic checks and named accountable owners hold scoped gates. No agent is a general-purpose gatekeeper.

Skills

• choose-work-profile — recommend and ask for POC, Pilot, or Production before the first working stage.
• continue-dev-flow — load and advance only the selected route.
• chief-engineer — advise the next integrated delivery step when the route is unclear, blocked, or drifting.
• science-officer — provide bounded independent technical assurance.
• science-officer-em — legacy report-envelope compatibility only.
• adopt-dev-flow — bind or upgrade a brownfield repository without replacing its existing authorities.

Selection and promotion

Explore is a use of POC, not a separate workflow, stage, or profile. Choose POC when credible negative evidence could cancel or materially change the next commitment this item asks the Captain to accept.

The Captain selects a profile through the host's structured Ask UI when available, with plain chat as fallback. The authorized work-item actor commits a kc-dev-flow-work-profile/v3 receipt for every new choice before the first working stage. Selection is not deferred to ideation because POC has no ideation stage.

Promote POC to Pilot when accepted scope adds limited real users, persistent valuable state, reused shortcuts, beyond-session operation, or retry/recovery duty. Promote either lower profile to Production when production data or credentials, destructive external mutation, irreversible migration, a compatibility break that makes a consumer act, unattended operation, broad exposure, SLO/support, or release/rollback ownership enters accepted scope. That compatibility trigger is about the consumer's hands, not the publication: a change an existing consumer absorbs by taking the new version is ordinary Pilot delivery carrying a migration entry, while one that makes it edit its own configuration or rewrite its own records is Production.

Distribution and adoption

The script surface has four roles. Runtime helpers are the loader, POC close guard, and conditional PR handoff. *.test.py files are package self-tests used by release proof. Adopters copy no canonical runtime file; adapters for other planning providers and release gates stay outside the plugin directory. The repository contract classifies every kc-dev-flow Python script into exactly one of these roles, so an unowned script fails the gate.

Release proof

Published mode enforces that a candidate receipt is valid only for its exact tracked package snapshot. Run candidate mode on the clean release PR head after all kc-dev-flow and marketplace changes have landed. If that snapshot changes before the release tag is created, discard the receipt and rerun candidate mode on the final release PR head. After release-please creates the tag, run published mode against it with the retained receipt; local install sync waits for that check to pass.

scripts/profile-contract-loader.py is the closed route and loading mechanism. It resolves contract-manifest.json from its own installed package, validates the manifest's exact resource inventory, and hashes the manifest plus every declared byte. No host/cache discovery or repository contracts root participates. For a selected work item it emits exactly references/kernel.md, that profile's base.md, and that stage's contract — the build.md one carrying the typed implementation-exit observation. Its explicit --validate-admission mode additionally validates the canonical Development Brief for a new Pilot or Production admission, including a concrete bite:/consumer: line in the preamble. continue-dev-flow's new-admission dispatch (the first working-stage load after backlog) is the caller that adds this flag and stops the dispatch on refusal; a later stage's dispatch for an already-admitted item omits it. Default loading does not inspect acceptance headings. The design rationale owns the planning/execution explanation.

At a route's first working stage, the loader also requires one non-empty scalar grouping value — either release and release-readiness: ready, or the unchanged sprint and sprint-readiness: ready — in work-item frontmatter for the packaged Spacedock route. release names one journey release identifier, qualified as <journey>/<release-id> — a shape sprint's <product>/S<number> convention gestures at but does not itself enforce — scalar; shared or integration work keeps multiple origins in prose rather than a list. The loader refuses an unqualified release value by a named error (RELEASE_QUALIFIED_RE in profile-contract-loader.py); sprint carries no equivalent check. A work item must not carry both pairs — the loader refuses that combination by a named error rather than resolving it silently. Those are local execution mechanics, not planning evidence.

Everything else under references/ is conditional. Selecting a profile or installing the package activates none of it; a reference link is not activation.

Retained-document and project-context policy both carry a build obligation and are independently rechecked at validation. An unavailable provider cannot silently become a delivery failure.

adopt-dev-flow binds the Local Profile interface while preserving README policy, local mods, provider adapters, and state. The activated skill supplies its own loader path for each invocation without persisting an installation path. A state-owned stage pin fixes version and digest for the active attempt and records the stable entity slug rather than a host filesystem path; a compatible upgrade starts at the next boundary, while an incompatible Local Profile interface stops for refit before pin write or dispatch. An adopter moving from an earlier vendored layout follows MIGRATION.md.

Install through the kc-claude-plugins marketplace in Claude Code. Codex uses the co-shipped .codex-plugin manifest and the same skill and contract files.

Hermes Agent

KC Dev Flow ships both an Agent Plugins v1 plugin.json and a small native Hermes registration layer. Install the kc-dev-flow subdirectory through hermes plugins install; Hermes keeps the package disabled until an operator enables it. Once enabled, the native layer exposes the package skills with stable names such as kc-dev-flow:choose-work-profile and kc-dev-flow:continue-dev-flow.

The Hermes package is a distribution route, not a repository runtime fallback: the activated skill anchors the same installed manifest and loader while the adopter keeps only its Local Profile policy, local mods, adapters, and state.