smota · smota · Jul 29, 2026 · Jul 29, 2026
diff --git a/README.md b/README.md
@@ -65,6 +65,19 @@ Already adopted AgentFlow? Use [`docs/assisted-update.md`](docs/assisted-update.
 node bin/cli.mjs update-prompt --target /path/to/your-project
 ```
 
+## Cockpit Goal Command Center
+
+Cockpit is the optional, first-class Goal Command Center for AgentFlow SDLC. CLI/GitHub workflow remains authoritative and fully usable without starting Cockpit; Cockpit reads durable SDLC records and presents goals, readiness, role flow, releases, approvals, replay, follow-ups, and safe workflow actions.
+
+Start it when you want visual operations:
+
+```bash
+AGENTFLOW_REPOSITORIES=owner/repo agentflow-sdlc cockpit
+agentflow-sdlc cockpit doctor --json
+```
+
+Read more: [`docs/cockpit.md`](docs/cockpit.md) and [`docs/cockpit-concepts-and-rules.md`](docs/cockpit-concepts-and-rules.md).
+
 ## Documentation map
 
 | Need                                   | Go here                                                                        |
@@ -74,6 +87,7 @@ node bin/cli.mjs update-prompt --target /path/to/your-project
 | Install or evaluate                    | [`docs/get-started.md`](docs/get-started.md)                                   |
 | Run issue work or contribute           | [`docs/guides/contribution-workflow.md`](docs/guides/contribution-workflow.md) |
 | Learn intelligent collaboration        | [`docs/intelligent-collaboration.md`](docs/intelligent-collaboration.md)       |
+| Use optional Goal Command Center       | [`docs/cockpit.md`](docs/cockpit.md)                                           |
 | Follow the workflow contract           | [`docs/agent-workflow.md`](docs/agent-workflow.md)                             |
 | Follow issue rules                     | [`docs/issue-standards.md`](docs/issue-standards.md)                           |
 | Configure a project                    | [`docs/project-config.md`](docs/project-config.md)                             |
@@ -88,6 +102,7 @@ node bin/cli.mjs update-prompt --target /path/to/your-project
 - Role-agent packages: `agents/roles/`.
 - Workflow skills: `agents/workflows/orchestrate/`, `scan/`, and `intelligent-collaboration/`.
 - Validators and helpers under `scripts/` and `lib/`.
+- Optional Cockpit Goal Command Center: `agentflow-sdlc cockpit`.
 - Examples and eval scaffolding under `docs/examples/` and `agents/evals/`.
 
 ## Contributing

diff --git a/adapters/agy/manifest.json b/adapters/agy/manifest.json
@@ -5,6 +5,10 @@
   "harness": "agy",
   "entry": ".agents/skills",
   "skills": ["sdlc-definition", "sdlc-migration", "sdlc-audit"],
-  "commands": ["agentflow-sdlc sdlc validate", "agentflow-sdlc skills sync --harness agy"],
+  "commands": [
+    "agentflow-sdlc sdlc validate",
+    "agentflow-sdlc skills sync --harness agy",
+    "agentflow-sdlc cockpit doctor --json"
+  ],
   "settings": [".agy/settings.json"]
 }
diff --git a/adapters/claude-code/manifest.json b/adapters/claude-code/manifest.json
@@ -5,6 +5,10 @@
   "harness": "claude-code",
   "entry": ".claude/skills",
   "skills": ["sdlc-definition", "sdlc-migration", "sdlc-audit"],
-  "commands": ["agentflow-sdlc sdlc validate", "agentflow-sdlc skills sync --harness claude-code"],
+  "commands": [
+    "agentflow-sdlc sdlc validate",
+    "agentflow-sdlc skills sync --harness claude-code",
+    "agentflow-sdlc cockpit doctor --json"
+  ],
   "settings": [".claude/settings.json"]
 }
diff --git a/adapters/codex/manifest.json b/adapters/codex/manifest.json
@@ -5,6 +5,10 @@
   "harness": "codex",
   "entry": ".agents/skills",
   "skills": ["sdlc-definition", "sdlc-migration", "sdlc-audit"],
-  "commands": ["agentflow-sdlc sdlc validate", "agentflow-sdlc skills sync --harness codex"],
+  "commands": [
+    "agentflow-sdlc sdlc validate",
+    "agentflow-sdlc skills sync --harness codex",
+    "agentflow-sdlc cockpit doctor --json"
+  ],
   "settings": [".codex/hooks.json"]
 }
diff --git a/adapters/pi/manifest.json b/adapters/pi/manifest.json
@@ -5,6 +5,10 @@
   "harness": "pi",
   "entry": ".pi/skills",
   "skills": ["sdlc-definition", "sdlc-migration", "sdlc-audit"],
-  "commands": ["agentflow-sdlc sdlc validate", "agentflow-sdlc skills sync --harness pi"],
+  "commands": [
+    "agentflow-sdlc sdlc validate",
+    "agentflow-sdlc skills sync --harness pi",
+    "agentflow-sdlc cockpit doctor --json"
+  ],
   "settings": [".pi/settings.json"]
 }
diff --git a/bin/cli.mjs b/bin/cli.mjs
@@ -269,6 +269,31 @@ function handleSettings(rest, targetDir) {
   process.exit(2)
 }
 
+function handleCockpit(rest, targetDir) {
+  const [subcommand] = positionalArgs(rest)
+  const pass = rest.filter((arg) => arg !== subcommand)
+  if (subcommand === 'doctor') return runScript('scripts/cockpit-doctor.mjs', pass, targetDir)
+  if (!subcommand || subcommand === 'start') {
+    const result = spawnSync(
+      process.execPath,
+      [resolve(packageRoot, 'scripts/cockpit-server.mjs')],
+      {
+        stdio: 'inherit',
+        env: {
+          ...process.env,
+          AGENTFLOW_REPOSITORIES:
+            process.env.AGENTFLOW_REPOSITORIES || process.env.COCKPIT_REPOSITORIES || '',
+        },
+      },
+    )
+    process.exit(result.status ?? 1)
+  }
+  process.stderr.write(
+    `Usage:\n  agentflow-sdlc cockpit [start]\n  agentflow-sdlc cockpit doctor [--json]\n`,
+  )
+  process.exit(2)
+}
+
 function handleExtensions(rest, targetDir) {
   const [subcommand, selector] = positionalArgs(rest)
   const json = rest.includes('--json')
@@ -373,6 +398,10 @@ function main() {
   const [command, ...rest] = process.argv.slice(2)
   const targetDir = resolve(getFlag(rest, '--target', process.cwd()))
 
+  if (command === 'cockpit') {
+    handleCockpit(rest, targetDir)
+  }
+
   if (command === 'plugins') {
     handlePlugins(rest, targetDir)
   }
@@ -472,7 +501,7 @@ function main() {
   }
 
   process.stderr.write(
-    'Usage: agentflow-sdlc <init|sync|doctor|doctor-env|sdlc|skills|plugins|settings|extensions|onboarding-prompt|update-prompt|migrate-rename|release-plan|mark-merged> [path] [--target <dir>] [--json]\n',
+    'Usage: agentflow-sdlc <init|sync|doctor|doctor-env|sdlc|cockpit|skills|plugins|settings|extensions|onboarding-prompt|update-prompt|migrate-rename|release-plan|mark-merged> [path] [--target <dir>] [--json]\n',
   )
   process.exit(2)
 }

diff --git a/docs/cockpit.md b/docs/cockpit.md
@@ -2,7 +2,7 @@
 
 AgentFlow Cockpit is the optional Goal Command Center for goal-oriented SDLC delivery. It turns GitHub issues, epics, comments, PRs, role-pass evidence, validation, and follow-ups into goals, evidence health, role flow contributions, graph navigation, next-best-actions, and replayable goal stories.
 
-Cockpit is optional. The CLI/GitHub workflow remains authoritative and fully usable without Cockpit.
+Cockpit is optional at runtime and first-class in the AgentFlow SDLC product. The CLI/GitHub workflow remains authoritative and fully usable without Cockpit. `init`, `sync`, `doctor`, validators, skills, plugins, and settings merge must not require a running Cockpit server.
 
 For the implemented product vocabulary and rules, see [`docs/cockpit-concepts-and-rules.md`](cockpit-concepts-and-rules.md). Use that document when reviewing SDLC roles, skills, and agents.
 
@@ -16,6 +16,16 @@ For the implemented product vocabulary and rules, see [`docs/cockpit-concepts-an
 - Follow-up issues are first-class; hidden TODOs are not.
 - No raw model transcripts, prompts, tool inputs, secrets, or hidden runner state in the UI.
 
+## CLI
+
+```bash
+AGENTFLOW_REPOSITORIES=owner/repo agentflow-sdlc cockpit
+agentflow-sdlc cockpit doctor --json
+node scripts/cockpit-smoke.mjs
+```
+
+`cockpit doctor` validates package files and runtime configuration. `cockpit-smoke` is a release gate that starts the server, checks `/healthz`, and verifies packaged assets.
+
 ## MVP authentication
 
 Remote-capable Cockpit uses GitHub OAuth as the MVP authentication option.

diff --git a/docs/index.md b/docs/index.md
@@ -4,26 +4,28 @@ This index maps the main concepts, defaults, roles, skills/workflows, templates,
 
 ## Start here
 
-1. [`../README.md`](../README.md)  concise front door: value, first steps, and document map.
-2. [`start-here.md`](start-here.md)  route humans and agents to the right document.
-3. [`agentflow-in-5-minutes.md`](agentflow-in-5-minutes.md)  short public explainer for the problem, lifecycle, primary evaluation path, and evidence model.
-4. [`get-started.md`](get-started.md)  assisted onboarding, install, configuration, sync, and verification path.
-5. [`assisted-onboarding.md`](assisted-onboarding.md)  LLM-assisted setup for existing projects with read-only inspection and explicit approval before changes.
-6. [`assisted-update.md`](assisted-update.md)  LLM-assisted update workflow for already-adopted projects using `agent-framework-lock.json`, `doctor`, `sync`, and `mark-merged`. [`deterministic-assisted-update.md`](deterministic-assisted-update.md) documents the proposed deterministic update-plan direction.
-7. [`environment-tools.md`](environment-tools.md)  required, recommended, and optional tools compatible with `doctor-env`.
-8. [`../AGENTS.md`](../AGENTS.md)  required first-read repository policy.
-9. [`project-setup.md`](project-setup.md)  guided setup choices for agents, execution mode, routing, branch strategy, validation, bounded work, and skill provenance.
-10. [`agent-workflow.md`](agent-workflow.md)  phase model, role-pass contract, durable evidence, branch strategy, review model, and PR readiness.
-11. [`issue-standards.md`](issue-standards.md)  issue titles, labels, body update rules, and lifecycle metadata.
-12. [`project-config.md`](project-config.md)  project-local `agent-workflow.config.json` contract.
-13. [`execution-targets.md`](execution-targets.md)  `executionTarget`, `transport`, `launcher`, `executor`, and `delegationBoundary` concepts that disambiguate `with claude`/`with agy`/`with pi` requests.
-14. [`capabilities.md`](capabilities.md)  portable PLAN/WORKFLOW/LOOP/SUB-AGENTS capability vocabulary, resolution modes, evidence, and adapter links.
-15. [`intelligent-collaboration.md`](intelligent-collaboration.md)  collaboration modes, decision budget, smallest-sufficient-collaboration rule, bounded helper intelligence, and compact evidence guidance.
-16. [`release-versioning.md`](release-versioning.md)  configurable release strategy, default `main.minor.fix`, release evidence, validators, and preview helpers.
-17. [`extension-packs.md`](extension-packs.md)  repository-level contrib-style overlays for opinionated engineering approaches, skills, tools, templates, and validators.
-18. [`examples/simple-bugfix-flow.md`](examples/simple-bugfix-flow.md), [`examples/multi-agent-review-flow.md`](examples/multi-agent-review-flow.md), [`examples/high-assurance-flow.md`](examples/high-assurance-flow.md), and [`examples/intelligent-collaboration-flow.md`](examples/intelligent-collaboration-flow.md)  public example flows and evidence excerpts.
-19. [`default-skills.md`](default-skills.md)  default skills, recommended companion skills, upstream repositories, and CCPM-sourced skill surfaces.
-20. [`../agents/agentflow-sdlc/README.md`](../agents/agentflow-sdlc/README.md)  canonical portable AgentFlow SDLC agent package with maturity, capability, handoff, eval, and improvement-loop contracts.
+1. [`../README.md`](../README.md) ï¿½ concise front door: value, first steps, and document map.
+2. [`start-here.md`](start-here.md) ï¿½ route humans and agents to the right document.
+3. [`agentflow-in-5-minutes.md`](agentflow-in-5-minutes.md) ï¿½ short public explainer for the problem, lifecycle, primary evaluation path, and evidence model.
+4. [`get-started.md`](get-started.md) ï¿½ assisted onboarding, install, configuration, sync, and verification path.
+5. [`assisted-onboarding.md`](assisted-onboarding.md) ï¿½ LLM-assisted setup for existing projects with read-only inspection and explicit approval before changes.
+6. [`assisted-update.md`](assisted-update.md) ï¿½ LLM-assisted update workflow for already-adopted projects using `agent-framework-lock.json`, `doctor`, `sync`, and `mark-merged`. [`deterministic-assisted-update.md`](deterministic-assisted-update.md) documents the proposed deterministic update-plan direction.
+7. [`environment-tools.md`](environment-tools.md) ï¿½ required, recommended, and optional tools compatible with `doctor-env`.
+8. [`../AGENTS.md`](../AGENTS.md) ï¿½ required first-read repository policy.
+9. [`project-setup.md`](project-setup.md) ï¿½ guided setup choices for agents, execution mode, routing, branch strategy, validation, bounded work, and skill provenance.
+10. [`agent-workflow.md`](agent-workflow.md) ï¿½ phase model, role-pass contract, durable evidence, branch strategy, review model, and PR readiness.
+11. [`issue-standards.md`](issue-standards.md) ï¿½ issue titles, labels, body update rules, and lifecycle metadata.
+12. [`project-config.md`](project-config.md) ï¿½ project-local `agent-workflow.config.json` contract.
+13. [`execution-targets.md`](execution-targets.md) ï¿½ `executionTarget`, `transport`, `launcher`, `executor`, and `delegationBoundary` concepts that disambiguate `with claude`/`with agy`/`with pi` requests.
+14. [`capabilities.md`](capabilities.md) ï¿½ portable PLAN/WORKFLOW/LOOP/SUB-AGENTS capability vocabulary, resolution modes, evidence, and adapter links.
+15. [`intelligent-collaboration.md`](intelligent-collaboration.md) ï¿½ collaboration modes, decision budget, smallest-sufficient-collaboration rule, bounded helper intelligence, and compact evidence guidance.
+16. [`release-versioning.md`](release-versioning.md) ï¿½ configurable release strategy, default `main.minor.fix`, release evidence, validators, and preview helpers.
+17. [`cockpit.md`](cockpit.md) ï¿½ optional first-class Goal Command Center for visual goal, readiness, release, replay, and approval operations.
+18. [`cockpit-concepts-and-rules.md`](cockpit-concepts-and-rules.md) ï¿½ Cockpit product language, safety, action, and support-boundary rules.
+19. [`extension-packs.md`](extension-packs.md) ï¿½ repository-level contrib-style overlays for opinionated engineering approaches, skills, tools, templates, and validators.
+20. [`examples/simple-bugfix-flow.md`](examples/simple-bugfix-flow.md), [`examples/multi-agent-review-flow.md`](examples/multi-agent-review-flow.md), [`examples/high-assurance-flow.md`](examples/high-assurance-flow.md), and [`examples/intelligent-collaboration-flow.md`](examples/intelligent-collaboration-flow.md) ï¿½ public example flows and evidence excerpts.
+21. [`default-skills.md`](default-skills.md) ï¿½ default skills, recommended companion skills, upstream repositories, and CCPM-sourced skill surfaces.
+22. [`../agents/agentflow-sdlc/README.md`](../agents/agentflow-sdlc/README.md) ï¿½ canonical portable AgentFlow SDLC agent package with maturity, capability, handoff, eval, and improvement-loop contracts.
 
 ## What it is
 
@@ -64,6 +66,8 @@ Intelligent collaboration: [`intelligent-collaboration.md`](intelligent-collabor
 
 The framework also supports locally managed skills/tooling in consuming projects. Install workflow skills using your agent/skill manager, then use the sync CLI for hooks, templates, docs, and validators. See [`default-skills.md`](default-skills.md) for upstream source and provenance notes.
 
+Optional visual operations use Cockpit, the first-class Goal Command Center. Cockpit is package-owned and runtime opt-in; `init`, `sync`, `doctor`, validators, skills, plugins, and settings do not require starting it.
+
 ## Defaults
 
 | Area                  | Default                                                                                        |

diff --git a/docs/release-publishing.md b/docs/release-publishing.md
@@ -52,11 +52,23 @@ agentflow-sdlc settings status --harness all --json
 
 The merge engine preserves project-owned keys and only injects the `agentflowSdlc` managed object from `manifests/harness-settings.json`.
 
+## Cockpit gate
+
+Cockpit is optional at runtime and first-class in the product artifact. It must be packaged, documented, and smoke-tested, but default install must not start a server, require OAuth, or enable write actions.
+
+Run:
+
+```bash
+AGENTFLOW_REPOSITORIES=owner/repo agentflow-sdlc cockpit doctor --json
+node scripts/cockpit-smoke.mjs
+```
+
 ## Full v1 release gate
 
 ```bash
 pnpm test
 node scripts/sdlc-sandbox-smoke.mjs
+node scripts/cockpit-smoke.mjs
 node scripts/validate-npm-package.mjs
 agentflow-sdlc plugins validate --harness all --json
 agentflow-sdlc settings merge --harness all --dry-run

diff --git a/docs/sdlc-definition.md b/docs/sdlc-definition.md
@@ -13,22 +13,25 @@ Harness-specific directories such as `.pi`, `.claude`, `.agy`, and `.codex` are
 
 ## Core concepts
 
-| Concept                | Meaning                                                 | Durable sources                             |
-| ---------------------- | ------------------------------------------------------- | ------------------------------------------- |
-| Workspace              | Configured repository/project boundary                  | config, Cockpit query state                 |
-| Goal Group             | Parent objective/epic                                   | issue body, relationships                   |
-| Goal                   | Delivery objective with acceptance                      | issue body, labels, comments                |
-| Delivery               | Implementation and PR activity                          | PR, commits, checks                         |
-| Role Flow              | Ordered role contributions and returns                  | role-pass, workflow-status, handover        |
-| Readiness              | Path-aware applicable quality state                     | issue/PR evidence, checks                   |
-| Release                | Target, impact, assignment, released/unreleased state   | issue fields, milestone, PR/release records |
-| Human approval gate    | Explicit human decision required by high-assurance work | PR review or gate record                    |
-| Follow-up              | Deferred work tracked as issue                          | follow-up issue links                       |
-| Source                 | External durable record link                            | GitHub issue/PR/comment/check URLs          |
-| Guided workflow action | Preview-first safe update to durable workflow records   | Cockpit/action audit                        |
+| Concept                | Meaning                                                                | Durable sources                             |
+| ---------------------- | ---------------------------------------------------------------------- | ------------------------------------------- |
+| Workspace              | Configured repository/project boundary                                 | config, Cockpit query state                 |
+| Goal Group             | Parent objective/epic                                                  | issue body, relationships                   |
+| Goal                   | Delivery objective with acceptance                                     | issue body, labels, comments                |
+| Delivery               | Implementation and PR activity                                         | PR, commits, checks                         |
+| Role Flow              | Ordered role contributions and returns                                 | role-pass, workflow-status, handover        |
+| Readiness              | Path-aware applicable quality state                                    | issue/PR evidence, checks                   |
+| Release                | Target, impact, assignment, released/unreleased state                  | issue fields, milestone, PR/release records |
+| Human approval gate    | Explicit human decision required by high-assurance work                | PR review or gate record                    |
+| Follow-up              | Deferred work tracked as issue                                         | follow-up issue links                       |
+| Source                 | External durable record link                                           | GitHub issue/PR/comment/check URLs          |
+| Guided workflow action | Preview-first safe update to durable workflow records                  | Cockpit/action audit                        |
+| Cockpit                | Optional first-class Goal Command Center projecting durable SDLC state | package runtime, GitHub/CLI records         |
 
 GitHub is current storage substrate. Product language leads with AgentFlow concepts.
 
+Cockpit is an official optional projection of this model. It may visualize goals, readiness, role flow, release state, replay, approvals, and follow-ups, but it must not own unique SDLC state or be required by `init`, `sync`, `doctor`, validators, skills, plugins, or settings merge.
+
 ## Paths
 
 Canonical workflow profiles: