godpowers 3.0.0 → 3.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (132) hide show
  1. package/CHANGELOG.md +46 -3
  2. package/README.md +28 -24
  3. package/RELEASE.md +31 -50
  4. package/SKILL.md +75 -113
  5. package/agents/god-archaeologist.md +11 -0
  6. package/agents/god-architect.md +12 -0
  7. package/agents/god-auditor.md +13 -0
  8. package/agents/god-automation-engineer.md +13 -0
  9. package/agents/god-browser-tester.md +15 -0
  10. package/agents/god-context-writer.md +14 -0
  11. package/agents/god-coordinator.md +14 -0
  12. package/agents/god-debt-assessor.md +11 -0
  13. package/agents/god-debugger.md +13 -0
  14. package/agents/god-deploy-engineer.md +13 -0
  15. package/agents/god-deps-auditor.md +13 -0
  16. package/agents/god-design-reviewer.md +14 -0
  17. package/agents/god-designer.md +15 -0
  18. package/agents/god-docs-writer.md +13 -0
  19. package/agents/god-executor.md +14 -0
  20. package/agents/god-explorer.md +14 -0
  21. package/agents/god-greenfieldifier.md +13 -0
  22. package/agents/god-harden-auditor.md +12 -0
  23. package/agents/god-incident-investigator.md +13 -0
  24. package/agents/god-launch-strategist.md +14 -0
  25. package/agents/god-migration-strategist.md +13 -0
  26. package/agents/god-observability-engineer.md +14 -0
  27. package/agents/god-orchestrator.md +16 -2
  28. package/agents/god-org-context-loader.md +11 -0
  29. package/agents/god-planner.md +11 -0
  30. package/agents/god-pm.md +14 -0
  31. package/agents/god-quality-reviewer.md +12 -0
  32. package/agents/god-reconciler.md +14 -1
  33. package/agents/god-reconstructor.md +16 -0
  34. package/agents/god-repo-scaffolder.md +11 -0
  35. package/agents/god-retrospective.md +11 -0
  36. package/agents/god-roadmap-reconciler.md +42 -87
  37. package/agents/god-roadmap-updater.md +11 -0
  38. package/agents/god-roadmapper.md +12 -0
  39. package/agents/god-spec-reviewer.md +14 -0
  40. package/agents/god-spike-runner.md +13 -0
  41. package/agents/god-stack-selector.md +12 -0
  42. package/agents/god-standards-check.md +13 -0
  43. package/agents/god-storyteller.md +14 -0
  44. package/agents/god-updater.md +14 -0
  45. package/bin/install.js +10 -0
  46. package/lib/README.md +4 -0
  47. package/lib/agent-validator.js +67 -2
  48. package/lib/cli-dispatch.js +40 -1
  49. package/lib/command-families.js +10 -2
  50. package/lib/install-profiles.js +4 -1
  51. package/lib/installer-args.js +22 -0
  52. package/lib/recipe-coverage-sync.js +1 -1
  53. package/lib/release-surface-sync.js +3 -0
  54. package/lib/repo-doc-sync.js +1 -1
  55. package/lib/repo-surface-sync.js +3 -3
  56. package/lib/route-quality-sync.js +2 -2
  57. package/lib/router.js +6 -0
  58. package/lib/surface-profile.js +168 -0
  59. package/package.json +2 -2
  60. package/references/orchestration/GOD-MODE-RUNBOOK.md +9 -14
  61. package/references/orchestration/GOD-ORCHESTRATOR-RUNBOOK.md +43 -81
  62. package/references/shared/DASHBOARD-CONTRACT.md +66 -29
  63. package/references/shared/README.md +1 -1
  64. package/routing/god-demo.yaml +35 -0
  65. package/routing/god-first-run.yaml +34 -0
  66. package/routing/god-roadmap-check.yaml +2 -2
  67. package/routing/god-surface.yaml +39 -0
  68. package/routing/recipes/try-safely.yaml +26 -0
  69. package/skills/god-agent-audit.md +17 -15
  70. package/skills/god-arch.md +1 -3
  71. package/skills/god-archaeology.md +5 -6
  72. package/skills/god-audit.md +6 -7
  73. package/skills/god-automation-setup.md +6 -7
  74. package/skills/god-automation-status.md +6 -7
  75. package/skills/god-build.md +1 -3
  76. package/skills/god-context-scan.md +7 -8
  77. package/skills/god-demo.md +53 -0
  78. package/skills/god-deploy.md +1 -3
  79. package/skills/god-design-impact.md +5 -6
  80. package/skills/god-design.md +9 -3
  81. package/skills/god-discuss.md +5 -6
  82. package/skills/god-docs.md +5 -10
  83. package/skills/god-doctor.md +8 -9
  84. package/skills/god-dogfood.md +7 -10
  85. package/skills/god-explore.md +5 -7
  86. package/skills/god-feature.md +1 -3
  87. package/skills/god-first-run.md +64 -0
  88. package/skills/god-harden.md +1 -3
  89. package/skills/god-help.md +77 -51
  90. package/skills/god-hotfix.md +1 -3
  91. package/skills/god-hygiene.md +5 -6
  92. package/skills/god-launch.md +1 -3
  93. package/skills/god-lifecycle.md +11 -13
  94. package/skills/god-link.md +1 -3
  95. package/skills/god-list-assumptions.md +7 -8
  96. package/skills/god-locate.md +7 -8
  97. package/skills/god-map-codebase.md +5 -6
  98. package/skills/god-migrate.md +7 -18
  99. package/skills/god-mode.md +5 -0
  100. package/skills/god-next.md +16 -17
  101. package/skills/god-observe.md +1 -3
  102. package/skills/god-prd.md +1 -3
  103. package/skills/god-preflight.md +7 -8
  104. package/skills/god-progress.md +7 -8
  105. package/skills/god-reconcile.md +9 -10
  106. package/skills/god-reconstruct.md +5 -7
  107. package/skills/god-redo.md +1 -3
  108. package/skills/god-refactor.md +7 -10
  109. package/skills/god-repair.md +1 -3
  110. package/skills/god-repo.md +1 -3
  111. package/skills/god-restore.md +1 -3
  112. package/skills/god-roadmap-check.md +10 -10
  113. package/skills/god-roadmap.md +1 -3
  114. package/skills/god-rollback.md +1 -3
  115. package/skills/god-scan.md +6 -12
  116. package/skills/god-skip.md +1 -3
  117. package/skills/god-spike.md +5 -6
  118. package/skills/god-stack.md +1 -3
  119. package/skills/god-standards.md +5 -6
  120. package/skills/god-status.md +12 -10
  121. package/skills/god-story-build.md +1 -3
  122. package/skills/god-story-close.md +1 -3
  123. package/skills/god-story.md +1 -3
  124. package/skills/god-surface.md +61 -0
  125. package/skills/god-sync.md +7 -13
  126. package/skills/god-tech-debt.md +5 -6
  127. package/skills/god-test-runtime.md +4 -8
  128. package/skills/god-undo.md +1 -3
  129. package/skills/god-update-deps.md +1 -3
  130. package/skills/god-upgrade.md +1 -3
  131. package/skills/god-version.md +1 -1
  132. package/skills/god.md +53 -52
@@ -1,90 +1,50 @@
1
1
  ---
2
2
  name: god-roadmap-reconciler
3
3
  description: |
4
- Reconciles user intent against ROADMAP.md before any feature work begins.
5
- Classifies intent as: already-done, enhancement, prerequisite-needed, or new.
6
- Prevents duplicate work, bypassed dependencies, and roadmap drift.
7
-
8
- Spawned by: /god-roadmap-check, recipe execution (feature-addition category)
9
- tools: Read, Bash, Grep, Glob
4
+ Legacy compatibility adapter for roadmap-only reconciliation. The
5
+ comprehensive god-reconciler owns the implementation because Phase 2 did
6
+ not record standalone /god-roadmap-check use and Phase 5 deprecated
7
+ /god-roadmap-check in favor of /god-reconcile.
8
+
9
+ Spawned by: legacy /god-roadmap-check installs only
10
+ tools: Read, Bash, Grep, Glob, Task
11
+ inputs:
12
+ - ".godpowers/roadmap/ROADMAP.md"
13
+ - ".godpowers/state.json"
14
+ - "user feature intent"
15
+ - "optional PRD evidence"
16
+ outputs:
17
+ - "roadmap reconciliation verdict from god-reconciler"
18
+ gates:
19
+ - "god-reconciler roadmap verdict"
20
+ - "no legacy-only classification logic"
21
+ handoff:
22
+ - "spawn god-reconciler with roadmap-only scope and return its verdict"
10
23
  ---
11
24
 
12
25
  # God Roadmap Reconciler
13
26
 
14
- Before doing feature work, ask: does this overlap with ROADMAP.md?
27
+ This agent is a compatibility adapter. Use `god-reconciler` for the actual
28
+ classification logic.
15
29
 
16
30
  ## Inputs
17
31
 
18
- - User intent (one paragraph describing what they want)
19
- - `.godpowers/roadmap/ROADMAP.md` (the existing roadmap)
20
- - `.godpowers/state.json` (to know lifecycle phase)
21
- - Optional: `.godpowers/prd/PRD.md` (to check requirement coverage)
32
+ - User intent as one paragraph.
33
+ - `.godpowers/roadmap/ROADMAP.md`.
34
+ - `.godpowers/state.json`.
35
+ - Optional `.godpowers/prd/PRD.md`.
22
36
 
23
37
  ## Process
24
38
 
25
- ### 1. Read ROADMAP.md
26
-
27
- Parse milestones from Now / Next / Later sections. Extract:
28
- - Each milestone's goal and features
29
- - The increment's `**Status**:` field (pending/building/done)
30
- - The member PRD requirement ids from its `**Features (from PRD)**:` list
31
- - Status (in-progress / planned / themed)
32
- - Dependencies between milestones
33
-
34
- ### 2. Match intent against existing milestones
35
-
36
- For each milestone, check if the user intent overlaps:
37
- - **Keyword match**: do feature names overlap? ("export", "csv", "download")
38
- - **Semantic match**: same user-facing behavior described differently?
39
- - **Requirement match**: does PRD.md already include this requirement?
40
-
41
- Also weigh the increment's `**Status**:` and its member requirement ids: an
42
- increment marked `done`, or one whose `**Features (from PRD)**:` ids already
43
- cover the intent, signals already-done or already-committed work rather than
44
- something new.
45
-
46
- ### 3. Classify
47
-
48
- Pick exactly one:
49
-
50
- #### Status: ALREADY-DONE
51
- Intent maps to a feature in a completed milestone (status = done).
52
- - Action: tell user "this exists"; show where in the codebase
53
- - Recommend: /god-status to verify; /god-graph trace to find code
54
-
55
- #### Status: IN-PROGRESS
56
- Intent maps to a feature in the current Now milestone (status = in-flight).
57
- - Action: tell user the work is already underway
58
- - Recommend: /god-status to check progress; /god-build to continue
39
+ 1. Treat this agent as deprecated compatibility surface.
40
+ 2. Spawn `god-reconciler` in fresh context with the same user intent.
41
+ 3. Tell `god-reconciler` to include the standard ROADMAP row in its verdict.
42
+ 4. If the caller is legacy `/god-roadmap-check`, return only the ROADMAP
43
+ verdict and recommendation fields.
59
44
 
60
- #### Status: ENHANCEMENT
61
- Intent extends a feature already in a milestone (planned or done).
62
- - Action: tell user this should be folded into that milestone
63
- - Recommend: /god-feature scoped to the existing milestone, OR
64
- /god-roadmap update to amend the milestone with the enhancement
45
+ ## Outputs
65
46
 
66
- #### Status: PREREQUISITE-NEEDED
67
- Intent depends on a milestone that's not yet complete.
68
- - Action: tell user the prerequisite
69
- - Recommend: complete prerequisite first via its workflow, OR
70
- defer this work to /god-add-backlog and surface it later
71
-
72
- #### Status: NEW
73
- Intent doesn't overlap with anything in ROADMAP.md.
74
- - Action: confirm it's genuinely new, ask where it belongs
75
- - Recommend: 4 options:
76
- - Add to current milestone (Now): /god-roadmap update
77
- - Add as next milestone (Next): /god-roadmap update
78
- - Park in backlog: /god-add-backlog
79
- - Plant a seed for the future: /god-plant-seed
80
-
81
- #### Status: AMBIGUOUS
82
- Multiple plausible matches; can't pick one.
83
- - Action: present matches to user; ask them to disambiguate
84
-
85
- ### 4. Output
86
-
87
- Return structured JSON to the orchestrating skill:
47
+ Return the ROADMAP portion of the `god-reconciler` verdict:
88
48
 
89
49
  ```json
90
50
  {
@@ -107,24 +67,19 @@ Return structured JSON to the orchestrating skill:
107
67
  }
108
68
  ```
109
69
 
70
+ ## Handoff
71
+
72
+ Spawn `god-reconciler` for all new roadmap overlap checks.
73
+
110
74
  ## Have-Nots
111
75
 
112
76
  Reconciliation FAILS if:
113
- - Returns "new" when there's clearly an existing milestone covering it
114
- - Returns "already-done" without checking actual completion status
115
- - Recommends bypassing a milestone's normal workflow without justification
116
- - No prerequisite check when one exists
117
- - Uses keyword-match alone without semantic check
118
- - Doesn't surface ambiguous cases for user to resolve
77
+ - This adapter performs independent classification instead of delegating.
78
+ - The returned ROADMAP status is not one of the canonical six statuses.
79
+ - The verdict omits the matching milestone or reason.
80
+ - The recommendation bypasses normal Godpowers workflow without justification.
81
+ - Ambiguous matches are hidden from the caller.
119
82
 
120
83
  ## When to skip reconciliation
121
84
 
122
- The orchestrator should skip this agent in cases where reconciliation would be noise:
123
-
124
- - `/god-fast` (trivial, not feature-level)
125
- - `/god-quick` (small task, may be too small to roadmap)
126
- - `/god-debug` (not a new feature)
127
- - `/god-hotfix` (urgent; reconcile after, in postmortem)
128
- - Recipes in non-feature-addition categories (recovering, meta, etc.)
129
-
130
- For feature-addition category recipes: ALWAYS reconcile first.
85
+ Follow the skip policy in `agents/god-reconciler.md`.
@@ -7,6 +7,17 @@ description: |
7
7
 
8
8
  Spawned by: end of feature-addition recipe execution, /god-roadmap update
9
9
  tools: Read, Write, Edit, Bash, Grep, Glob
10
+ inputs:
11
+ - ".godpowers/roadmap/ROADMAP.md"
12
+ - "completed feature change description"
13
+ outputs:
14
+ - "updated .godpowers/roadmap/ROADMAP.md"
15
+ - "roadmap changelog entry"
16
+ gates:
17
+ - "roadmap update have-nots"
18
+ - "PRD linkage retained"
19
+ handoff:
20
+ - "return roadmap update summary and downstream sync notes"
10
21
  ---
11
22
 
12
23
  # God Roadmap Updater
@@ -7,6 +7,18 @@ description: |
7
7
 
8
8
  Spawned by: /god-roadmap, god-orchestrator
9
9
  tools: Read, Write, Bash, Grep
10
+ inputs:
11
+ - ".godpowers/prd/PRD.md"
12
+ - ".godpowers/arch/ARCH.md"
13
+ - "templates/ROADMAP.md"
14
+ outputs:
15
+ - ".godpowers/roadmap/ROADMAP.md"
16
+ gates:
17
+ - "R-01 through R-10 have-nots"
18
+ - "topological dependency ordering"
19
+ - "observable completion gates"
20
+ handoff:
21
+ - "return roadmap and pause only for capacity or ordering ambiguity"
10
22
  ---
11
23
 
12
24
  # God Roadmapper
@@ -7,6 +7,20 @@ description: |
7
7
 
8
8
  Spawned by: god-orchestrator (after god-executor completes a slice)
9
9
  tools: Read, Bash, Grep, Glob
10
+ inputs:
11
+ - "slice plan"
12
+ - "PRD acceptance criteria"
13
+ - "executor code diff"
14
+ - "request-trace evidence"
15
+ outputs:
16
+ - "stage 1 PASS or FAIL verdict"
17
+ - "spec compliance findings"
18
+ gates:
19
+ - "scope compliance"
20
+ - "acceptance criteria coverage"
21
+ - "no unrelated churn"
22
+ handoff:
23
+ - "return verdict to orchestrator for quality review or repair"
10
24
  ---
11
25
 
12
26
  # God Spec Reviewer (Stage 1)
@@ -8,6 +8,19 @@ description: |
8
8
 
9
9
  Spawned by: /god-spike
10
10
  tools: Read, Write, Edit, Bash, Grep, Glob, WebSearch
11
+ inputs:
12
+ - "specific technical question"
13
+ - "time-box"
14
+ - "minimal relevant context"
15
+ outputs:
16
+ - ".godpowers/spikes/<slug>/SPIKE.md"
17
+ - "throwaway proof-of-concept code"
18
+ gates:
19
+ - "SP-01 through SP-05 have-nots"
20
+ - "evidence-backed recommendation"
21
+ - "time-box respected"
22
+ handoff:
23
+ - "return proceed, reject, or follow-up spike recommendation"
11
24
  ---
12
25
 
13
26
  # God Spike Runner
@@ -6,6 +6,18 @@ description: |
6
6
 
7
7
  Spawned by: /god-stack, god-orchestrator
8
8
  tools: Read, Write, Bash, Grep, WebSearch
9
+ inputs:
10
+ - ".godpowers/arch/ARCH.md"
11
+ - "optional org constraints"
12
+ - "optional imported stack signals"
13
+ outputs:
14
+ - ".godpowers/stack/DECISION.md"
15
+ gates:
16
+ - "S-01 through S-05 have-nots"
17
+ - "scored candidates and flip points"
18
+ - "lock-in cost evidence"
19
+ handoff:
20
+ - "return stack decision and pause only for close tradeoffs or lock-in choices"
9
21
  ---
10
22
 
11
23
  # God Stack Selector
@@ -7,6 +7,19 @@ description: |
7
7
 
8
8
  Spawned by: skill orchestration after any artifact-producing agent
9
9
  tools: Read, Grep, Glob
10
+ inputs:
11
+ - "just-produced artifact"
12
+ - "applicable have-nots list"
13
+ - "routing gate configuration"
14
+ outputs:
15
+ - "PASS, FAIL, or PARTIAL verdict"
16
+ - "standards findings"
17
+ gates:
18
+ - "substitution test"
19
+ - "three-label test"
20
+ - "artifact-specific have-nots"
21
+ handoff:
22
+ - "return gate behavior and remediation path to orchestrating skill"
10
23
  ---
11
24
 
12
25
  # God Standards Check
@@ -8,6 +8,20 @@ description: |
8
8
 
9
9
  Spawned by: /god-story, /god-feature --with-stories
10
10
  tools: Read, Write, Bash, Grep
11
+ inputs:
12
+ - "user story prompt"
13
+ - "feature decomposition"
14
+ - "optional PRD and roadmap context"
15
+ outputs:
16
+ - "STORY.md content"
17
+ - "acceptance criteria"
18
+ - "initial slice plan"
19
+ gates:
20
+ - "user-story format"
21
+ - "runtime-test-friendly acceptance criteria"
22
+ - "linkage participation"
23
+ handoff:
24
+ - "return story artifact and suggested build or feature next step"
11
25
  ---
12
26
 
13
27
  # God Storyteller
@@ -10,6 +10,20 @@ description: |
10
10
 
11
11
  Spawned by: /god-sync, end of feature-addition recipe execution
12
12
  tools: Read, Write, Edit, Bash, Grep, Glob, Task
13
+ inputs:
14
+ - "reconciliation verdict"
15
+ - "changed files"
16
+ - "trigger type and recent commits"
17
+ outputs:
18
+ - "updated affected artifacts"
19
+ - ".godpowers/SYNC-LOG.md"
20
+ - "local sync summaries"
21
+ gates:
22
+ - "per-artifact have-nots"
23
+ - "feature awareness and source sync-back freshness"
24
+ - "no broad context loading"
25
+ handoff:
26
+ - "return sync summary and remaining artifact drift if any"
13
27
  ---
14
28
 
15
29
  # God Updater
package/bin/install.js CHANGED
@@ -58,6 +58,8 @@ function showHelp() {
58
58
  log(' automation-status Show host automation provider support');
59
59
  log(' automation-setup Show an opt-in automation setup plan');
60
60
  log(' dogfood Run built-in messy-repo dogfood scenarios');
61
+ log(' demo Show the shipped sandbox proof');
62
+ log(' surface Preview or apply an installed command profile');
61
63
  log(' extension-scaffold Create a publishable extension pack skeleton');
62
64
  log('');
63
65
  log('Command families:');
@@ -72,6 +74,10 @@ function showHelp() {
72
74
  log(' --tier=<name> Tier for gate: prd, design, arch, roadmap, stack, repo, build, or harden');
73
75
  log(' --json Emit JSON for status, next, proof, or automation commands');
74
76
  log(' --brief Render compact output for status, next, or proof');
77
+ log(' --full Render complete output for status, next, or demo');
78
+ log(' --dry-run Preview a surface profile change');
79
+ log(' --apply Apply a surface profile change');
80
+ log(' --runtime=<name> Runtime target for surface, such as codex');
75
81
  log(' --name=<scope/name> Extension package name for extension-scaffold');
76
82
  log(' --output=<path> Extension output root for extension-scaffold');
77
83
  log(' --skill=<name> Extension skill name for extension-scaffold');
@@ -110,6 +116,8 @@ function showHelp() {
110
116
  log(' npx godpowers automation-status --project=.');
111
117
  log(' npx godpowers automation-setup --project=.');
112
118
  log(' npx godpowers dogfood');
119
+ log(' npx godpowers demo --project=.');
120
+ log(' npx godpowers surface --profile=builder --codex --global --dry-run');
113
121
  log(' npx godpowers extension-scaffold --name=@godpowers/my-pack --output=.');
114
122
  log(' npx godpowers --claude --global');
115
123
  log(' npx godpowers --claude --global --profile=core');
@@ -216,7 +224,9 @@ module.exports = {
216
224
  runAutomationCommand: cliDispatch.runAutomationCommand,
217
225
  runDashboardCommand: cliDispatch.runDashboardCommand,
218
226
  runDogfoodCommand: cliDispatch.runDogfoodCommand,
227
+ runDemoCommand: cliDispatch.runDemoCommand,
219
228
  runQuickProofCommand: cliDispatch.runQuickProofCommand,
229
+ runSurfaceCommand: cliDispatch.runSurfaceCommand,
220
230
  runMcpInfoCommand: cliDispatch.runMcpInfoCommand,
221
231
  runExtensionScaffoldCommand: cliDispatch.runExtensionScaffoldCommand,
222
232
  runGateCommand: cliDispatch.runGateCommand,
package/lib/README.md CHANGED
@@ -59,8 +59,10 @@ package-level integrations.
59
59
 
60
60
  | Module | Purpose |
61
61
  |--------|---------|
62
+ | `artifact-map.js` | Centralize canonical artifact paths for dashboards, gates, and helpers. |
62
63
  | `artifact-linter.js` | Check artifacts for required labels, evidence, and domain precision. |
63
64
  | `artifact-diff.js` | Compare artifact changes for review and release workflows. |
65
+ | `gate.js` | Run executable artifact gates for Phase 1 tier completion checks. |
64
66
  | `have-nots-validator.js` | Check artifacts against known failure modes. |
65
67
  | `meta-linter.js` | Validate Godpowers documentation and skill metadata. |
66
68
  | `story-validator.js` | Validate story artifacts and story lifecycle state. |
@@ -108,7 +110,9 @@ package-level integrations.
108
110
  | `installer-core.js` | Install and uninstall the Godpowers surface for each runtime. |
109
111
  | `installer-files.js` | File-copy helpers shared by the installer and its tests. |
110
112
  | `installer-args.js` | Parse `bin/install.js` arguments and subcommands. |
113
+ | `cli-dispatch.js` | Dispatch local CLI helper commands such as status, quick-proof, gate, dogfood, and extension-scaffold. |
111
114
  | `install-profiles.js` | Select smaller role-specific slash-command install surfaces. |
115
+ | `surface-profile.js` | Preview and apply runtime command surface profile switches after install. |
112
116
  | `installer-runtimes.js` | Map supported runtimes to their config directories. |
113
117
  | `package-identity.js` | Centralize package name, version, repository, docs, and command identity. |
114
118
  | `automation-providers.js` | Detect and configure host-native automation providers. |
@@ -22,6 +22,7 @@ const frontmatter = require('./frontmatter');
22
22
 
23
23
  const REQUIRED_FRONTMATTER = ['name', 'description'];
24
24
  const RECOMMENDED_FRONTMATTER = ['tools'];
25
+ const STRUCTURED_CONTRACT_FRONTMATTER = ['inputs', 'outputs', 'gates', 'handoff'];
25
26
  const RECOMMENDED_SECTIONS = ['Have-Nots', 'Inputs', 'Outputs', 'Handoff'];
26
27
 
27
28
  /**
@@ -68,6 +69,7 @@ function parseAgentFile(filePath) {
68
69
  */
69
70
  function validateAgent(agent, opts = {}) {
70
71
  const findings = [];
72
+ const contractSeverity = opts.contractSeverity || 'info';
71
73
 
72
74
  // Required frontmatter
73
75
  for (const field of REQUIRED_FRONTMATTER) {
@@ -93,6 +95,30 @@ function validateAgent(agent, opts = {}) {
93
95
  }
94
96
  }
95
97
 
98
+ // Structured contract frontmatter
99
+ for (const field of STRUCTURED_CONTRACT_FRONTMATTER) {
100
+ const value = agent.frontmatter[field];
101
+ if (!value) {
102
+ findings.push({
103
+ severity: contractSeverity,
104
+ kind: 'missing-contract-frontmatter',
105
+ agent: agent.name,
106
+ field,
107
+ message: `Missing contract frontmatter field: \`${field}\``
108
+ });
109
+ continue;
110
+ }
111
+ if (!Array.isArray(value) || value.length === 0 || value.some(item => typeof item !== 'string' || !item.trim())) {
112
+ findings.push({
113
+ severity: contractSeverity,
114
+ kind: 'invalid-contract-frontmatter',
115
+ agent: agent.name,
116
+ field,
117
+ message: `Contract frontmatter field \`${field}\` must be a non-empty string array.`
118
+ });
119
+ }
120
+ }
121
+
96
122
  // Recommended sections (case-insensitive substring match)
97
123
  const sectionTitles = Object.keys(agent.sections).map(s => s.toLowerCase());
98
124
  for (const section of RECOMMENDED_SECTIONS) {
@@ -114,6 +140,15 @@ function validateAgent(agent, opts = {}) {
114
140
  return findings;
115
141
  }
116
142
 
143
+ function hasStructuredContract(agent) {
144
+ return STRUCTURED_CONTRACT_FRONTMATTER.every(field => {
145
+ const value = agent.frontmatter[field];
146
+ return Array.isArray(value) &&
147
+ value.length > 0 &&
148
+ value.every(item => typeof item === 'string' && item.trim());
149
+ });
150
+ }
151
+
117
152
  /**
118
153
  * Extract claimed hand-off targets (other agents this agent spawns).
119
154
  */
@@ -133,11 +168,33 @@ function findHandoffTargets(agent) {
133
168
  return [...targets];
134
169
  }
135
170
 
171
+ function extractPathClaims(text) {
172
+ const paths = new Set();
173
+ const dotPathRegex = /\.godpowers\/[\w\/.-]+(?:\.(?:md|json|jsonl|yaml))?/g;
174
+ let m;
175
+ while ((m = dotPathRegex.exec(text)) !== null) {
176
+ paths.add(m[0]);
177
+ }
178
+ const rootRegex = /\b[A-Z]+\.md\b/g;
179
+ while ((m = rootRegex.exec(text)) !== null) {
180
+ paths.add(m[0]);
181
+ }
182
+ return [...paths];
183
+ }
184
+
136
185
  /**
137
186
  * Extract output paths the agent claims to write.
138
187
  */
139
188
  function findOutputPaths(agent) {
140
189
  const paths = new Set();
190
+ if (Array.isArray(agent.frontmatter.outputs)) {
191
+ for (const output of agent.frontmatter.outputs) {
192
+ if (typeof output !== 'string') continue;
193
+ for (const out of extractPathClaims(output)) paths.add(out);
194
+ }
195
+ return [...paths];
196
+ }
197
+
141
198
  const text = agent.raw;
142
199
 
143
200
  // .godpowers/*.md or .godpowers/*.json
@@ -218,11 +275,15 @@ function auditAll(projectRoot, opts = {}) {
218
275
  }
219
276
  const files = fs.readdirSync(agentsDir).filter(f => /^god-.*\.md$/.test(f));
220
277
  const agents = files.map(f => parseAgentFile(path.join(agentsDir, f)));
278
+ const structuredContractCount = agents.filter(hasStructuredContract).length;
279
+ const contractWarningThreshold = opts.contractWarningThreshold || 20;
280
+ const contractSeverity = opts.contractSeverity ||
281
+ (structuredContractCount >= contractWarningThreshold ? 'warning' : 'info');
221
282
 
222
283
  const allFindings = [];
223
284
  const results = [];
224
285
  for (const agent of agents) {
225
- const f = validateAgent(agent, opts);
286
+ const f = validateAgent(agent, { ...opts, contractSeverity });
226
287
  results.push({ agent: agent.name, findings: f });
227
288
  allFindings.push(...f);
228
289
  }
@@ -235,7 +296,9 @@ function auditAll(projectRoot, opts = {}) {
235
296
  warnings: allFindings.filter(f => f.severity === 'warning').length,
236
297
  infos: allFindings.filter(f => f.severity === 'info').length,
237
298
  crossFindings,
238
- agentCount: agents.length
299
+ agentCount: agents.length,
300
+ structuredContractCount,
301
+ contractWarningThreshold
239
302
  };
240
303
 
241
304
  return { results, summary, allFindings };
@@ -248,7 +311,9 @@ module.exports = {
248
311
  findOutputPaths,
249
312
  crossValidate,
250
313
  auditAll,
314
+ hasStructuredContract,
251
315
  REQUIRED_FRONTMATTER,
252
316
  RECOMMENDED_FRONTMATTER,
317
+ STRUCTURED_CONTRACT_FRONTMATTER,
253
318
  RECOMMENDED_SECTIONS
254
319
  };
@@ -46,7 +46,7 @@ function runDashboardCommand(opts) {
46
46
  return;
47
47
  }
48
48
 
49
- console.log(dashboard.render(result, { brief: opts.brief }));
49
+ console.log(dashboard.render(result, { brief: opts.brief || !opts.full }));
50
50
  if (opts.command === 'next') {
51
51
  console.log('');
52
52
  console.log('Suggested next command:');
@@ -65,6 +65,10 @@ function runDogfoodCommand(opts) {
65
65
  if (result.status !== 'pass') process.exit(1);
66
66
  }
67
67
 
68
+ function runDemoCommand(opts) {
69
+ return runQuickProofCommand({ ...opts, brief: opts.full ? false : true });
70
+ }
71
+
68
72
  function runQuickProofCommand(opts) {
69
73
  const quickProof = require('./quick-proof');
70
74
  const result = quickProof.compute(opts.project);
@@ -75,6 +79,37 @@ function runQuickProofCommand(opts) {
75
79
  }
76
80
  }
77
81
 
82
+ function runSurfaceCommand(opts) {
83
+ const path = require('path');
84
+ const surfaceProfile = require('./surface-profile');
85
+ const srcDir = path.resolve(__dirname, '..');
86
+ let applied = [];
87
+
88
+ if (opts.apply) {
89
+ if (opts.json) {
90
+ const originalLog = console.log;
91
+ const originalError = console.error;
92
+ console.log = () => {};
93
+ console.error = () => {};
94
+ try {
95
+ applied = surfaceProfile.apply(srcDir, opts);
96
+ } finally {
97
+ console.log = originalLog;
98
+ console.error = originalError;
99
+ }
100
+ } else {
101
+ applied = surfaceProfile.apply(srcDir, opts);
102
+ }
103
+ }
104
+
105
+ const result = surfaceProfile.plan(srcDir, opts);
106
+ if (opts.json) {
107
+ console.log(JSON.stringify({ ...result, applied }, null, 2));
108
+ } else {
109
+ console.log(surfaceProfile.render(result));
110
+ }
111
+ }
112
+
78
113
  function runMcpInfoCommand(opts) {
79
114
  const mcpInfo = require('./mcp-info');
80
115
  const result = mcpInfo.info(opts.project);
@@ -185,6 +220,8 @@ const COMMAND_RUNNERS = {
185
220
  'automation-status': runAutomationCommand,
186
221
  'automation-setup': runAutomationCommand,
187
222
  dogfood: runDogfoodCommand,
223
+ demo: runDemoCommand,
224
+ surface: runSurfaceCommand,
188
225
  'extension-scaffold': runExtensionScaffoldCommand,
189
226
  gate: runGateCommand
190
227
  };
@@ -204,7 +241,9 @@ module.exports = {
204
241
  runAutomationCommand,
205
242
  runDashboardCommand,
206
243
  runDogfoodCommand,
244
+ runDemoCommand,
207
245
  runQuickProofCommand,
246
+ runSurfaceCommand,
208
247
  runMcpInfoCommand,
209
248
  runExtensionScaffoldCommand,
210
249
  runGateCommand,
@@ -15,6 +15,8 @@ const COMMAND_FAMILIES = [
15
15
  purpose: 'Start or import a project.',
16
16
  commands: [
17
17
  '/god',
18
+ '/god-first-run',
19
+ '/god-demo',
18
20
  '/god-init',
19
21
  '/god-mode',
20
22
  '/god-plan',
@@ -191,6 +193,7 @@ const COMMAND_FAMILIES = [
191
193
  purpose: 'Tune settings, budgets, cache, profiles, help, and version info.',
192
194
  commands: [
193
195
  '/god-settings',
196
+ '/god-surface',
194
197
  '/god-set-profile',
195
198
  '/god-budget',
196
199
  '/god-cost',
@@ -292,9 +295,14 @@ function familyForCommand(command) {
292
295
  return COMMAND_FAMILIES.find((family) => family.commands.includes(command)) || null;
293
296
  }
294
297
 
295
- function renderFamilyCards(families = COMMAND_FAMILIES.filter((family) => family.visibility !== 'hidden')) {
298
+ function renderFamilyCards(
299
+ families = COMMAND_FAMILIES.filter((family) => family.visibility !== 'hidden'),
300
+ opts = {}
301
+ ) {
296
302
  return families.map((family) => (
297
- `${family.label}: ${family.purpose} (${family.commands.join(', ')})`
303
+ opts.includeCommands
304
+ ? `${family.label}: ${family.purpose} (${family.commands.join(', ')})`
305
+ : `${family.label}: ${family.purpose}`
298
306
  ));
299
307
  }
300
308
 
@@ -1,6 +1,9 @@
1
1
  const COMMON = [
2
2
  'god',
3
+ 'god-first-run',
4
+ 'god-demo',
3
5
  'god-help',
6
+ 'god-surface',
4
7
  'god-version',
5
8
  'god-status'
6
9
  ];
@@ -131,7 +134,7 @@ const PROFILE_SKILLS = {
131
134
  };
132
135
 
133
136
  const PROFILE_DESCRIPTIONS = {
134
- core: 'front door, status, verbs, and autonomous compatibility',
137
+ core: 'first-run guidance, front door, status, verbs, surface control, and autonomous compatibility',
135
138
  builder: 'core plus planning leaves, stories, and runtime verification',
136
139
  maintainer: 'core plus hygiene, deps, docs, repair, automation, and extensions',
137
140
  suite: 'core plus multi-repo suite and workstream coordination',