godpowers 1.6.5 → 1.6.7

package/AGENTS.md

@@ -35,3 +35,13 @@ projects from raw idea to hardened production.
 - No emojis (use `+`, `-`, `x`, `!` for status indicators)
 - Every sentence in generated artifacts must be labeled: DECISION, HYPOTHESIS, or OPEN QUESTION
 - Every claim must fail the substitution test (swap in a competitor, sentence must break)
+
+<!-- pillars:begin -->
+## Godpowers Pillars Protocol
+
+- [DECISION] Load `agents/context.md` and `agents/repo.md` before Godpowers commands make durable project decisions.
+- [DECISION] Load additional `agents/*.md` pillar files only when their frontmatter matches the task.
+- [DECISION] Treat `.godpowers/state.json`, `.godpowers/PROGRESS.md`, and `.godpowers/CHECKPOINT.md` as workflow state.
+- [DECISION] Treat Pillars files as portable project context for any coding agent that opens this repository.
+- [DECISION] Disk state wins over conversation memory when these sources disagree.
+<!-- pillars:end -->

package/CHANGELOG.md

@@ -5,6 +5,72 @@ All notable changes to Godpowers will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.6.7] - 2026-05-16
+
+Progress visibility patch. Makes Godpowers easier to follow while preserving
+the stable 1.6 command surface.
+
+### Added
+- Added `lib/state.progressSummary`, `orderedSubSteps`, and
+  `renderProgressLine` so commands can report percentage complete, completed
+  step count, total step count, and current step number from state.json.
+- Added checkpoint frontmatter fields for `progress-pct`,
+  `progress-complete`, `progress-total`, and `current-step`.
+- Added `CHECKPOINT.md` sections for recent work and what happens next.
+- Added a Step Narration Protocol for `god-orchestrator` so visible
+  tier/sub-step work gets compact "Next step" and "Step result" cards.
+- Added `/god-mode`, `/god-next`, `/god-status`, and `/god-locate` guidance
+  for progress, path-ahead, recent work, and next-action summaries.
+- Added `PROGRESS.md` template sections for the current step plan and recent
+  step results.
+- Added root `AGENTS.md` Pillars Protocol guidance so coding agents know which
+  project context and workflow-state files are authoritative.
+- Added installer coverage for `--local` Codex installs.
+- Added regression coverage for progress math, checkpoint progress rendering,
+  checkpoint progress preservation, and checkpoint step summaries.
+
+### Changed
+- Package publication now allowlists `agents/god-*.md` instead of the entire
+  `agents/` directory so local Pillars files do not enter the npm payload.
+- Package contents checks now fail when non-specialist files under `agents/`
+  would be included in the npm package.
+- The installer now resolves local runtime destinations when `--local` is used
+  and only installs specialist agent files matching `god-*.md`.
+
+### Guardrails
+- This patch does not add slash commands, specialist agents, workflows,
+  recipes, schemas, or public artifact formats.
+- Progress percentages are derived from disk state, not conversation memory.
+- Optional or intentionally skipped steps count as complete when their state
+  is `imported`, `skipped`, or `not-required`.
+
+## [1.6.6] - 2026-05-16
+
+Non-God-Mode handoff privacy patch. Extends the display-safe handoff pattern
+from `/god-mode` to other orchestrator entrypoints.
+
+### Added
+- Added private handoff guidance for `/god-init` before it spawns
+  `god-orchestrator`.
+- Added private handoff guidance for `/god-suite-init`,
+  `/god-suite-release`, and `/god-suite-patch` before they spawn
+  `god-coordinator`.
+- Added `god-coordinator` guidance for display-safe per-repo
+  `god-orchestrator` spawns.
+- Added regression coverage for non-`/god-mode` handoff entrypoints.
+
+### Changed
+- `god-orchestrator` now documents handoff files from `/god-init`,
+  `god-coordinator`, or any other caller, not only `/god-mode`.
+- `/god-hygiene` routing no longer lists `god-orchestrator` as a secondary
+  spawn because the skill only runs the three hygiene audits.
+
+### Guardrails
+- This patch does not add slash commands, agents, workflows, recipes, schemas,
+  or public artifact formats.
+- The handoff change affects transcript hygiene only. It does not weaken
+  release-truth gates or per-repo Quarterback ownership.
+
 ## [1.6.5] - 2026-05-16
 
 God Mode handoff privacy patch. Keeps the 1.6 command surface stable while

package/README.md

@@ -2,7 +2,7 @@
 
 [![CI](https://github.com/aihxp/godpowers/actions/workflows/ci.yml/badge.svg)](https://github.com/aihxp/godpowers/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
-[![Version](https://img.shields.io/badge/version-1.6.5-blue)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-1.6.7-blue)](CHANGELOG.md)
 [![npm](https://img.shields.io/npm/v/godpowers.svg)](https://www.npmjs.com/package/godpowers)
 
 **Ship fast. Ship right. Ship everything. Ship accountably.**
@@ -12,11 +12,10 @@ idea to hardened production. It runs as **slash commands inside your AI coding
 tool** (Claude Code, Codex, Cursor, etc.) that orchestrate **specialist agents**
 in fresh contexts to do the work.
 
-Version 1.6.5 keeps the stable Godpowers surface while making Codex
-`god-orchestrator` spawns transcript-safe: `/god-mode` now writes detailed
-orchestration context to a private handoff file and spawns with only a small
-display-safe pointer. Safe-sync and unresolved Critical harden findings still
-gate direct Tier 3 commands, `/god-mode`, and `/god-mode --yolo`.
+Version 1.6.7 keeps the stable Godpowers surface while making the live arc
+easier to follow: progress reports now show percent complete, current step,
+recent work, and what happens next. The orchestrator also documents compact
+"Next step" and "Step result" cards around visible tier/sub-step work.
 
 It fuses four disciplines into one unified workflow:
 

package/RELEASE.md

@@ -1,11 +1,10 @@
-# Godpowers 1.6.5 Release
+# Godpowers 1.6.7 Release
 
 Date: 2026-05-16
 
-Godpowers 1.6.5 keeps the stable 1.6 surface while fixing Codex God Mode
-transcript hygiene. The goal of this patch is to make `god-orchestrator`
-spawn correctly from `/god-mode` and `/god-mode --yolo` without exposing the
-detailed orchestration payload in the visible transcript.
+Godpowers 1.6.7 makes the live workflow easier to track. The goal of this
+patch is to answer "what is Godpowers doing, how far along is it, what just
+happened, and what happens next" from disk state.
 
 ## What is stable
 
@@ -27,35 +26,47 @@ detailed orchestration payload in the visible transcript.
 
 ## What is new
 
-- `/god-mode` now writes detailed orchestration context to
-  `.godpowers/runs/<run-id>/ORCHESTRATOR-HANDOFF.md`.
-- `/god-mode` now spawns `god-orchestrator` with only a display-safe project
-  root, flags, and handoff file path.
-- `god-orchestrator` now knows to read the handoff file before planning,
-  spawning, or mutating project state.
-- `god-orchestrator` now treats handoff contents as private orchestration
-  context and keeps them out of the visible transcript.
-- Agent validation and smoke tests now inspect `agents/god-*.md` specialist
-  files while allowing Pillars context files like `agents/context.md` and
-  `agents/repo.md` to coexist.
-
-## What 1.6.5 means
-
-Godpowers 1.6.5 does not expand the public command surface. It fixes the Codex
-spawn integration path so the right specialist agent is still started, but the
-host UI only sees a small pointer to disk state instead of raw checkpoint,
-routing, and local-file details.
+- `lib/state.progressSummary` computes percentage complete, completed step
+  count, total step count, current step number, and current tier/sub-step from
+  `state.json`.
+- `CHECKPOINT.md` can persist progress frontmatter and now includes
+  "What happened recently" and "What happens next" sections.
+- `god-orchestrator` now has a Step Narration Protocol for compact
+  "Next step" and "Step result" cards around visible tier/sub-step work.
+- `/god-mode`, `/god-next`, `/god-status`, and `/god-locate` now document
+  progress, path-ahead, recent-work, and next-action summaries.
+- `templates/PROGRESS.md` now includes a current step plan and recent step
+  result shape.
+- Package publication now allowlists `agents/god-*.md`, preventing local
+  Pillars files under `agents/` from entering the npm payload.
+- Package contents checks now fail if non-specialist files under `agents/`
+  would be published.
+- `AGENTS.md` now includes the Pillars Protocol for loading durable project
+  context and workflow-state files.
+- Installer local mode now resolves runtime destinations under the current
+  directory and installs only `god-*.md` specialist agent files.
+
+## What 1.6.7 means
+
+Godpowers 1.6.7 does not expand the public command surface. It makes the
+existing arc more legible by showing a disk-derived progress report, a short
+plan before visible work starts, and a short result after work completes or
+pauses.
+
+The release also tightens npm packaging around specialist agents. Local
+project Pillars can live under `agents/` during development, but only
+`agents/god-*.md` files are packaged as Godpowers specialist agents.
 
 Safe sync and unresolved Critical harden findings remain release-truth gates.
-`--yolo` can still auto-pick defaults, but it cannot bypass those blockers.
+Per-repo Quarterback ownership remains intact for Mode D suite work.
 
 ## Stability policy
 
 During the 1.x stability window, do not add broad new command families, change
 schema formats, or rename public artifacts without evidence from real use.
 
-The `v1.6.5` git tag points to the release commit that matches the npm
-`godpowers@1.6.5` package. Public publishes should prefer the tag-triggered
+The `v1.6.7` git tag points to the release commit that matches the npm
+`godpowers@1.6.7` package. Public publishes should prefer the tag-triggered
 GitHub workflow so npm provenance, git history, and release notes stay aligned.
 
 Allowed changes:

package/agents/god-coordinator.md

@@ -44,6 +44,20 @@ suite (the collection of repos), not individual repos.
 - Per-repo `state.json` files
 - Optionally: a specific operation (sync, release, patch, status)
 
+## Coordinator Handoff
+
+When spawned by a suite command, the visible spawn message may include only a
+display-safe operation summary plus a path like
+`.godpowers/runs/<run-id>/COORDINATOR-HANDOFF.md`.
+
+If a handoff path is provided:
+1. Read the handoff file before planning, spawning, or mutating suite state.
+2. Treat the handoff as private suite coordination context.
+3. Do not quote, summarize, or expose the full handoff in the visible
+   transcript.
+4. If the handoff conflicts with durable suite artifacts, prefer disk
+   artifacts and record the conflict as an open question or repair target.
+
 ## Process per operation
 
 ### Mode 1: status (`/god-suite-status`)
@@ -66,7 +80,8 @@ suite (the collection of repos), not individual repos.
 
 1. User provides repo + new version
 2. Run impact analysis: which sibling repos depend on this one?
-3. For each affected sibling: spawn its `god-orchestrator` with a
+3. For each affected sibling: write a per-repo orchestrator handoff file and
+   spawn its `god-orchestrator` with only a display-safe pointer for the
    `version-bump` directive (NOT a full arc)
 4. Aggregate results into a release report
 5. Update `.godpowers/suite-config.yaml` version-table
@@ -75,8 +90,9 @@ suite (the collection of repos), not individual repos.
 ### Mode 4: patch (`/god-suite-patch`)
 
 1. User describes a change that touches multiple repos
-2. For each repo in scope: spawn its `god-orchestrator` with the
-   patch description
+2. For each repo in scope: write a per-repo orchestrator handoff file and
+   spawn its `god-orchestrator` with only a display-safe pointer for the
+   patch directive
 3. Coordinate atomicity: if any repo fails, mark the suite-level
    patch as incomplete and report
 4. Append to SYNC-LOG.md
@@ -117,8 +133,25 @@ For each operation, return to the spawning skill with:
 ## Coordination with per-repo orchestrators
 
 When you need work done IN a repo (version bump, patch slice, etc.),
-spawn that repo's `god-orchestrator` via the Task tool with the
-specific directive. Do not bypass it. The Quarterback rule:
+create a private handoff in that repo first, then spawn that repo's
+`god-orchestrator` via the Task tool with only a display-safe pointer.
+
+Per-repo handoff path:
+`.godpowers/runs/<run-id>/COORDINATOR-ORCHESTRATOR-HANDOFF.md`
+
+Put the version-bump directive, patch directive, suite impact analysis,
+affected dependency facts, release notes, and repo-specific notes in the
+handoff file. The visible spawn message may include only:
+- The target repo root
+- The suite operation name
+- The handoff file path
+- "Read the handoff file first, then run the requested scoped work from disk
+  state. Return only user-facing progress and final status."
+
+Do not put suite metadata, dependency graphs, local file lists, release notes,
+patch descriptions, hidden routing rules, or detailed instructions in the
+visible spawn message. Do not bypass the target repo orchestrator. The
+Quarterback rule:
 
 > Each repo has exactly one orchestrator. The coordinator is a peer
 > at suite scope, not a higher-tier overseer.

package/agents/god-orchestrator.md

@@ -21,10 +21,11 @@ You orchestrate the full Godpowers arc. You DO NOT do the heavy lifting yourself
 Your job is to spawn the right specialist agent for each sub-step, verify their
 output passes the gate, update PROGRESS.md, and move to the next step.
 
-## God Mode Handoff
+## Orchestrator Handoff
 
-When spawned by `/god-mode`, the visible spawn message may include only a
-display-safe summary plus a path like
+When spawned by `/god-mode`, `/god-init`, `god-coordinator`, or any other
+caller, the visible spawn message may include only a display-safe summary plus
+a path like
 `.godpowers/runs/<run-id>/ORCHESTRATOR-HANDOFF.md`.
 
 If a handoff path is provided:
@@ -469,13 +470,16 @@ for `STAGING_APP_URL=<deployed staging origin>` before deployed staging smoke.
 1. Read .godpowers/PROGRESS.md (or create it if absent)
 2. Identify the first non-done tier sub-step
 3. Verify upstream gate (artifact on disk, passes have-nots)
-4. Spawn the appropriate specialist agent in a fresh context
-5. Verify their output exists on disk
-6. Run have-nots check on the artifact
-7. If pass: update PROGRESS.md, move to next sub-step
-8. If fail and repairable: enter the autonomous repair loop
-9. If fail and human-only: pause with the smallest needed question
-10. Repeat until all tiers complete and verification is green
+4. Print the "Next step" card from the Step Narration Protocol
+5. Spawn the appropriate specialist agent in a fresh context
+6. Verify their output exists on disk
+7. Run have-nots check on the artifact
+8. If pass: update PROGRESS.md, sync CHECKPOINT.md, print the "Step result"
+   card, then move to next sub-step
+9. If fail and repairable: print the failed result card, then enter the
+   autonomous repair loop
+10. If fail and human-only: pause with the smallest needed question
+11. Repeat until all tiers complete and verification is green
 ```
 
 ## Specialist Agent Routing
@@ -704,6 +708,8 @@ debugger. Keep orchestration scaffolding private.
 
 Show:
 - concise phase status
+- before each visible tier/sub-step, a short "what will happen" card
+- after each visible tier/sub-step, a short "what happened" card
 - durable state detected from disk
 - commands being run and whether they passed or failed
 - scoped file changes
@@ -723,6 +729,51 @@ user-facing question. Do not expose the rule itself. Example: ask for
 `STAGING_APP_URL=<deployed staging origin>` rather than showing the Shipping
 Closure Protocol.
 
+## Step Narration Protocol
+
+Godpowers must make its work trackable without exposing hidden prompts or
+internal routing payloads. Before and after each visible tier/sub-step, print
+one compact card.
+
+Before starting a tier/sub-step:
+
+```
+Next step
+Progress: <pct>% (<done> of <total> steps complete; current step <n> of <total>)
+Tier: <tier-number> <tier-label>
+Step: <sub-step-label>
+Why this now: <one sentence tied to disk state or the prior gate>
+What will happen:
+  1. <first observable action>
+  2. <second observable action>
+  3. <third observable action, if needed>
+Expected output: <artifact path or verification result>
+```
+
+After a tier/sub-step completes or pauses:
+
+```
+Step result
+Progress: <pct>% (<done> of <total> steps complete; current step <n> of <total>)
+Tier: <tier-number> <tier-label>
+Step: <sub-step-label>
+Result: <done | blocked | failed | skipped | imported>
+What happened:
+  1. <observable action completed>
+  2. <artifact or state update>
+  3. <verification result>
+Next: <next command or pause question>
+```
+
+Rules:
+- Keep each card under 12 lines unless a pause needs options.
+- Use `lib/state.progressSummary(stateJson)` for the percentage and step count
+  whenever state.json is available.
+- Use artifact paths and verification evidence from disk, not memory.
+- Do not print raw Task input, hidden instructions, or full file loadout lists.
+- If a step is blocked, do not show a generic "Suggested next"; show the
+  smallest concrete unblock action.
+
 ## Resume Protocol
 
 On every invocation:

package/bin/install.js

@@ -118,6 +118,16 @@ const RUNTIMES = {
   },
 };
 
+function resolveRuntime(runtimeKey, opts = {}) {
+  const runtime = RUNTIMES[runtimeKey];
+  if (!runtime) return null;
+  const resolved = { ...runtime };
+  if (opts.local && !opts.global) {
+    resolved.configDir = path.join(process.cwd(), path.basename(runtime.configDir));
+  }
+  return resolved;
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -331,8 +341,8 @@ function parseArgs(argv) {
 // Install
 // ---------------------------------------------------------------------------
 
-function installForRuntime(runtimeKey, srcDir) {
-  const runtime = RUNTIMES[runtimeKey];
+function installForRuntime(runtimeKey, srcDir, opts = {}) {
+  const runtime = resolveRuntime(runtimeKey, opts);
   if (!runtime) {
     error(`Unknown runtime: ${runtimeKey}`);
     return false;
@@ -367,7 +377,7 @@ function installForRuntime(runtimeKey, srcDir) {
     ensureDir(agentsDest);
     let count = 0;
     for (const file of fs.readdirSync(agentsSrc)) {
-      if (file.endsWith('.md')) {
+      if (/^god-.*\.md$/.test(file)) {
         const srcFile = path.join(agentsSrc, file);
         installAgentFile(srcFile, agentsDest, runtime);
         count++;
@@ -456,8 +466,8 @@ function installForRuntime(runtimeKey, srcDir) {
 // Uninstall
 // ---------------------------------------------------------------------------
 
-function uninstallForRuntime(runtimeKey) {
-  const runtime = RUNTIMES[runtimeKey];
+function uninstallForRuntime(runtimeKey, opts = {}) {
+  const runtime = resolveRuntime(runtimeKey, opts);
   if (!runtime) {
     error(`Unknown runtime: ${runtimeKey}`);
     return false;
@@ -580,16 +590,16 @@ function main() {
 
   const srcDir = path.resolve(__dirname, '..');
 
-  // Detect non-interactive and default to claude global
+  // Detect non-interactive and default to Claude Code.
   if (opts.runtimes.length === 0 && !opts.all) {
     if (!process.stdin.isTTY) {
-      warn('Non-interactive terminal detected, defaulting to Claude Code global install');
+      warn('Non-interactive terminal detected, defaulting to Claude Code install');
       opts.runtimes = ['claude'];
-      opts.global = true;
+      if (!opts.local) opts.global = true;
     } else {
       // Interactive mode: default to claude
       opts.runtimes = ['claude'];
-      opts.global = true;
+      if (!opts.local) opts.global = true;
     }
   }
 
@@ -601,7 +611,7 @@ function main() {
   if (opts.uninstall) {
     let removed = 0;
     for (const runtime of opts.runtimes) {
-      if (uninstallForRuntime(runtime)) {
+      if (uninstallForRuntime(runtime, opts)) {
         removed++;
       }
     }
@@ -617,7 +627,7 @@ function main() {
 
   let installed = 0;
   for (const runtime of opts.runtimes) {
-    if (installForRuntime(runtime, srcDir)) {
+    if (installForRuntime(runtime, srcDir, opts)) {
       installed++;
     }
   }
@@ -625,7 +635,7 @@ function main() {
   if (installed > 0) {
     // Count slash commands for verification message
     const skillsCount = fs.readdirSync(path.join(srcDir, 'skills')).filter(f => f.endsWith('.md')).length;
-    const agentsCount = fs.readdirSync(path.join(srcDir, 'agents')).filter(f => f.endsWith('.md')).length;
+    const agentsCount = fs.readdirSync(path.join(srcDir, 'agents')).filter(f => /^god-.*\.md$/.test(f)).length;
 
     log('');
     log(`\x1b[32mDone!\x1b[0m Installed Godpowers v${VERSION} for ${installed} runtime(s).`);

package/lib/checkpoint.js

@@ -22,6 +22,10 @@
  *     lifecycle: {pre-init|in-arc|steady-state-active|...}
  *     current-tier: {tier-N}
  *     current-substep: {substep-key}
+ *     progress-pct: {number}
+ *     progress-complete: {number}
+ *     progress-total: {number}
+ *     current-step: {number}
  *     last-action: {action-name}
  *     last-actor: {agent or user}
  *     last-update: {ISO8601}
@@ -123,6 +127,7 @@ function write(projectRoot, state) {
   const actions = (state.actions || []).slice(0, MAX_ACTIONS);
   const facts = (state.facts || []).slice(0, MAX_FACTS);
   const factsHash = sha256(JSON.stringify(facts));
+  const progress = state.progress || null;
 
   const fm = [
     '---',
@@ -133,13 +138,27 @@ function write(projectRoot, state) {
     `lifecycle: ${state.lifecycle || 'in-arc'}`,
     `current-tier: ${state.currentTier || 'tier-0'}`,
     `current-substep: ${state.currentSubstep || 'orchestration'}`,
+    progress ? `progress-pct: ${progress.percent}` : null,
+    progress ? `progress-complete: ${progress.completed}` : null,
+    progress ? `progress-total: ${progress.total}` : null,
+    progress ? `current-step: ${progress.currentStep}` : null,
     `last-action: ${state.lastAction || 'unknown'}`,
     `last-actor: ${state.lastActor || 'unknown'}`,
     `last-update: ${ts}`,
     `facts-hash: sha256:${factsHash}`,
     '---',
     ''
-  ].join('\n');
+  ].filter(line => line !== null).join('\n');
+
+  const progressLine = progress
+    ? `- Progress: **${progress.percent}%** (${progress.completed} of ${progress.total} steps complete; current step ${progress.currentStep} of ${progress.total})`
+    : null;
+  const recentSummary = actions.length === 0
+    ? '_(no recent actions recorded yet)_'
+    : actions.slice(0, 3).map(a => `- ${a}`).join('\n');
+  const nextSummary = state.nextCommand
+    ? `- ${state.nextCommand}\n- ${state.nextReason || 'No reason recorded.'}`
+    : '- Run `/god-next` to compute the next command from disk state.';
 
   const body = [
     '# Checkpoint',
@@ -153,9 +172,18 @@ function write(projectRoot, state) {
     `- Project: **${state.project || 'unnamed'}**`,
     `- Mode: **${state.mode || '?'}**${state.modeDSuite ? ' (in multi-repo suite)' : ''}`,
     `- Lifecycle phase: **${state.lifecycle || 'in-arc'}**`,
+    progressLine,
     `- Current tier: **${state.currentTier || 'tier-0'}** / **${state.currentSubstep || 'orchestration'}**`,
     `- Last action: \`${state.lastAction || 'unknown'}\` by ${state.lastActor || 'unknown'} at ${ts}`,
     '',
+    '## What happened recently',
+    '',
+    recentSummary,
+    '',
+    '## What happens next',
+    '',
+    nextSummary,
+    '',
     '## Next suggested command',
     '',
     state.nextCommand
@@ -191,7 +219,7 @@ function write(projectRoot, state) {
     `- Authoritative state: \`.godpowers/state.json\``,
     `- Authoritative history: \`.godpowers/runs/<id>/events.jsonl\` + \`.godpowers/log\``,
     ''
-  ].join('\n');
+  ].filter(line => line !== null).join('\n');
 
   fs.writeFileSync(file, fm + body);
   return file;
@@ -234,7 +262,7 @@ function recordFact(projectRoot, fact) {
 }
 
 function frontmatterToState(fm, facts) {
-  return {
+  const result = {
     project: fm.project,
     mode: fm.mode,
     modeDSuite: fm['mode-d-suite'] === true || fm['mode-d-suite'] === 'true',
@@ -245,6 +273,15 @@ function frontmatterToState(fm, facts) {
     lastActor: fm['last-actor'],
     facts: facts || []
   };
+  if (fm['progress-total']) {
+    result.progress = {
+      percent: Number(fm['progress-pct'] || 0),
+      completed: Number(fm['progress-complete'] || 0),
+      total: Number(fm['progress-total'] || 0),
+      currentStep: Number(fm['current-step'] || 0)
+    };
+  }
+  return result;
 }
 
 /**
@@ -304,27 +341,26 @@ function syncFromState(projectRoot, opts = {}) {
 
   const s = state.read(projectRoot);
   if (!s) throw new Error('state.json not initialized');
+  const progress = state.progressSummary(s);
 
-  // Find the current tier + sub-step: first one with status in-flight,
-  // else last one done, else tier-0/orchestration.
+  // Find the current tier + sub-step from progressSummary, then keep a
+  // separate lastAction pointer to the newest completed step.
   let currentTier = 'tier-0';
   let currentSubstep = 'orchestration';
   let lastAction = 'init';
   let lastUpdate = null;
   let lastActor = 'unknown';
+  if (progress.current) {
+    currentTier = progress.current.tierKey;
+    currentSubstep = progress.current.subStepKey;
+  }
+
   if (s.tiers) {
-    outer: for (const tierKey of Object.keys(s.tiers).sort()) {
+    for (const tierKey of Object.keys(s.tiers).sort()) {
       for (const [substepKey, sub] of Object.entries(s.tiers[tierKey])) {
-        if (sub.status === 'in-flight') {
-          currentTier = tierKey;
-          currentSubstep = substepKey;
-          break outer;
-        }
         if (sub.status === 'done' && sub.updated) {
           if (!lastUpdate || sub.updated > lastUpdate) {
             lastUpdate = sub.updated;
-            currentTier = tierKey;
-            currentSubstep = substepKey;
             lastAction = `${tierKey}.${substepKey} done`;
           }
         }
@@ -372,6 +408,7 @@ function syncFromState(projectRoot, opts = {}) {
     lastActor,
     actions,
     facts,
+    progress,
     nextCommand: opts.nextCommand,
     nextReason: opts.nextReason
   });

package/lib/state.js

@@ -10,11 +10,52 @@ const path = require('path');
 const crypto = require('crypto');
 
 const STATE_VERSION = '1.0.0';
+const COMPLETE_STATUSES = new Set(['done', 'imported', 'skipped', 'not-required']);
+const ACTIVE_STATUSES = new Set(['in-flight', 'failed', 're-invoked']);
+const TIER_LABELS = {
+  'tier-0': 'Orchestration',
+  'tier-1': 'Planning',
+  'tier-2': 'Building',
+  'tier-3': 'Shipping'
+};
+const SUBSTEP_LABELS = {
+  orchestration: 'Orchestration',
+  prd: 'PRD',
+  arch: 'Architecture',
+  roadmap: 'Roadmap',
+  stack: 'Stack',
+  design: 'Design',
+  product: 'Product',
+  repo: 'Repo',
+  build: 'Build',
+  deploy: 'Deploy',
+  observe: 'Observe',
+  launch: 'Launch',
+  harden: 'Harden'
+};
 
 function statePath(projectRoot) {
   return path.join(projectRoot, '.godpowers', 'state.json');
 }
 
+function tierNumber(tierKey) {
+  const match = String(tierKey).match(/^tier-(\d+)$/);
+  return match ? Number(match[1]) : Number.MAX_SAFE_INTEGER;
+}
+
+function labelFromKey(key) {
+  return String(key)
+    .split(/[-_]/)
+    .filter(Boolean)
+    .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(' ');
+}
+
+function tierComparator(a, b) {
+  const byNumber = tierNumber(a) - tierNumber(b);
+  return byNumber === 0 ? String(a).localeCompare(String(b)) : byNumber;
+}
+
 /**
  * Read state.json from a project. Returns null if not initialized.
  */
@@ -139,4 +180,106 @@ function detectDrift(projectRoot) {
   return drift;
 }
 
-module.exports = { read, write, init, updateSubStep, hashFile, detectDrift, statePath };
+function isCompleteStatus(status) {
+  return COMPLETE_STATUSES.has(status);
+}
+
+function isActiveStatus(status) {
+  return ACTIVE_STATUSES.has(status);
+}
+
+function orderedSubSteps(state) {
+  if (!state || !state.tiers) return [];
+  const steps = [];
+  for (const tierKey of Object.keys(state.tiers).sort(tierComparator)) {
+    const tier = state.tiers[tierKey] || {};
+    for (const [subStepKey, subStep] of Object.entries(tier)) {
+      const status = subStep && subStep.status ? subStep.status : 'pending';
+      steps.push({
+        tierKey,
+        tierNumber: tierNumber(tierKey),
+        tierLabel: TIER_LABELS[tierKey] || labelFromKey(tierKey),
+        subStepKey,
+        subStepLabel: SUBSTEP_LABELS[subStepKey] || labelFromKey(subStepKey),
+        status,
+        artifact: subStep && subStep.artifact,
+        updated: subStep && subStep.updated
+      });
+    }
+  }
+  return steps.map((step, index) => ({ ...step, ordinal: index + 1 }));
+}
+
+function progressSummary(state) {
+  const steps = orderedSubSteps(state);
+  const total = steps.length;
+  const completed = steps.filter(step => isCompleteStatus(step.status)).length;
+
+  let currentIndex = steps.findIndex(step => isActiveStatus(step.status));
+  if (currentIndex < 0) {
+    currentIndex = steps.findIndex(step => !isCompleteStatus(step.status));
+  }
+  if (currentIndex < 0 && total > 0) currentIndex = total - 1;
+
+  const current = currentIndex >= 0 ? steps[currentIndex] : null;
+  return {
+    percent: total === 0 ? 0 : Math.round((completed / total) * 100),
+    completed,
+    total,
+    remaining: Math.max(total - completed, 0),
+    currentStep: current ? current.ordinal : 0,
+    current,
+    tiers: summarizeTiers(steps)
+  };
+}
+
+function summarizeTiers(steps) {
+  const byTier = new Map();
+  for (const step of steps) {
+    if (!byTier.has(step.tierKey)) {
+      byTier.set(step.tierKey, {
+        tierKey: step.tierKey,
+        tierNumber: step.tierNumber,
+        tierLabel: step.tierLabel,
+        completed: 0,
+        total: 0,
+        current: false
+      });
+    }
+    const tier = byTier.get(step.tierKey);
+    tier.total += 1;
+    if (isCompleteStatus(step.status)) tier.completed += 1;
+    if (isActiveStatus(step.status)) tier.current = true;
+  }
+  return Array.from(byTier.values()).map(tier => ({
+    ...tier,
+    percent: tier.total === 0 ? 0 : Math.round((tier.completed / tier.total) * 100)
+  }));
+}
+
+function renderProgressLine(summary) {
+  const progress = summary && typeof summary.total === 'number' ? summary : progressSummary(summary);
+  if (!progress || progress.total === 0) {
+    return 'Progress: unavailable, no tracked Godpowers steps found';
+  }
+  const current = progress.current;
+  const currentLabel = current
+    ? `${current.tierLabel} / ${current.subStepLabel}`
+    : 'complete';
+  return `Progress: ${progress.percent}% (${progress.completed} of ${progress.total} steps complete; current step ${progress.currentStep} of ${progress.total}: ${currentLabel})`;
+}
+
+module.exports = {
+  read,
+  write,
+  init,
+  updateSubStep,
+  hashFile,
+  detectDrift,
+  statePath,
+  orderedSubSteps,
+  progressSummary,
+  renderProgressLine,
+  isCompleteStatus,
+  isActiveStatus
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "godpowers",
-  "version": "1.6.5",
+  "version": "1.6.7",
   "description": "AI-powered development system: 106 slash commands and 39 specialist agents that take a project from raw idea to hardened production. Runs inside Claude Code, Codex, Cursor, Windsurf, Gemini, and 10+ other AI coding tools.",
   "bin": {
     "godpowers": "./bin/install.js"
@@ -66,7 +66,7 @@
   "files": [
     "bin/",
     "skills/",
-    "agents/",
+    "agents/god-*.md",
     "hooks/",
     "templates/",
     "references/",

package/routing/god-hygiene.yaml

@@ -12,7 +12,7 @@ prerequisites:
 execution:
   spawns: [god-auditor]
   context: fresh
-  secondary-spawns: [god-deps-auditor, god-docs-writer, god-orchestrator]
+  secondary-spawns: [god-deps-auditor, god-docs-writer]
   writes:
     - .godpowers/HYGIENE-REPORT.md
 

package/skills/god-doctor.md

@@ -48,7 +48,7 @@ GODPOWERS DOCTOR
 Install: claude (~/.claude/)
   [OK] 106 skills installed
   [OK] 39 agents installed
-  [OK] VERSION matches (1.6.5)
+  [OK] VERSION matches (1.6.6)
   [WARN] routing/god-doctor.yaml exists but skill file did not until now
 
 Project: /Users/.../my-project/.godpowers/

package/skills/god-init.md

@@ -81,10 +81,27 @@ needs to specify a mode.
    - Code present + org context: "Detected: existing codebase + org standards.
      I'll archaeology, reconstruct, and respect your org's standards."
 
-4. Ask the user to describe what they want to build. Accept any format.
-
-5. Spawn **god-orchestrator** in fresh context with the user's description and
-   the detected mode/context.
+5. Ask the user to describe what they want to build. Accept any format.
+
+6. Create a private disk handoff before spawning the orchestrator:
+   - Path: `.godpowers/runs/<run-id>/INIT-ORCHESTRATOR-HANDOFF.md`
+   - Create parent directories if needed.
+   - Put the user's description, detected mode, detected context, initial
+     findings summary, imported context summary, Pillars status, and next-step
+     routing notes in this file.
+
+7. Spawn **god-orchestrator** in fresh context with only a display-safe
+   payload:
+   - Name the project root.
+   - Name the invocation as `/god-init`.
+   - Name the handoff file path.
+   - Say: "Read the handoff file first, then initialize or resume from disk
+     state. Return only user-facing progress and final status."
+
+   Do not put recovered planning context, local file lists, org standards,
+   imported planning-system summaries, hidden routing rules, or detailed
+   instructions in the visible spawn message. Assume the host UI may display
+   the raw spawn message to the user.
 
    The orchestrator will:
    - Run Mode Detection (announced in plain English; stored as A/B/C/E internally)
@@ -100,14 +117,14 @@ needs to specify a mode.
    - Write PROGRESS.md with mode, scale, timestamp, tier states
    - Return mode/scale/announcement to this skill
 
-4. Detect scale by analyzing the description:
+8. Detect scale by analyzing the description:
    - **Trivial**: Single file change, bug fix, config tweak
    - **Small**: One feature, one service, <1 week
    - **Medium**: Multiple features, 1-3 services, 1-4 weeks
    - **Large**: Multiple services, team coordination, 1-3 months
    - **Enterprise**: Multiple teams, compliance, 3+ months
 
-5. Create the directory structure:
+9. Create the directory structure:
    ```
    AGENTS.md
    agents/
@@ -140,9 +157,9 @@ needs to specify a mode.
      harden/
    ```
 
-6. Write PROGRESS.md with mode, scale, timestamp, all tiers set to `pending`
+10. Write PROGRESS.md with mode, scale, timestamp, all tiers set to `pending`
 
-7. Report to the user:
+11. Report to the user:
    - Detected mode and scale
    - Which tiers and personas will activate
    - What to run next (suggest `god prd` or `god mode`)

package/skills/god-locate.md

@@ -40,6 +40,7 @@ GODPOWERS LOCATE
 
 Project: <name>  Mode: <A/B/C/E>  Suite: <yes/no>
 Lifecycle: <phase>  Current: <tier>/<substep>
+Progress: <pct>% (<complete> of <total> steps complete; current step <n> of <total>)
 
 Last action: <name> by <actor> at <ts>
 Last user instruction: <if available>
@@ -55,6 +56,14 @@ Recent events (last 5):
 - <event>
 - ...
 
+What happened recently:
+- <checkpoint action or event summary>
+- <checkpoint action or event summary>
+
+What happens next:
+- <next command>
+- <one-line reason>
+
 Next suggested: <command>
   Reason: <why>
 
@@ -73,8 +82,12 @@ Drift check:
 3. If state.json is missing: project is broken; run `/god-doctor`.
 4. Compute age of CHECKPOINT last-update; flag staleness if > 1 hour
    or > 100 events since last checkpoint write.
-5. Produce single-screen orientation summary.
-6. Append `op:locate` event to events.jsonl.
+5. Compute progress from `lib/state.progressSummary(stateJson)` and show
+   percentage, complete count, total count, and current step number.
+6. Summarize "what happened recently" from CHECKPOINT.md actions or recent
+   events, then summarize "what happens next" from routing.
+7. Produce single-screen orientation summary.
+8. Append `op:locate` event to events.jsonl.
 
 ## Difference from /god-status
 

package/skills/god-mode.md

@@ -164,6 +164,8 @@ The God Mode transcript is an operator console, not a prompt debugger.
 
 Show:
 - detected resume or project mode in plain language
+- a compact "Next step" card before each visible phase or tier sub-step
+- a compact "Step result" card after each visible phase or tier sub-step
 - short progress updates for phases, commands, validations, and file edits
 - concise validation summaries instead of full command noise when possible
 - final changed paths, validation results, and completion or pause status
@@ -182,6 +184,39 @@ smallest user-facing question. For example, ask for
 `STAGING_APP_URL=<deployed staging origin>` instead of exposing the full
 Shipping Closure Protocol.
 
+## Step Cards
+
+Relay the orchestrator's step cards when present. If the orchestrator output is
+missing them, synthesize them from disk state before continuing.
+
+Before work starts:
+
+```
+Next step
+Progress: <pct>% (<done> of <total> steps complete; current step <n> of <total>)
+Tier: <tier-number> <tier-label>
+Step: <sub-step-label>
+Why this now: <one sentence>
+What will happen:
+  1. <observable action>
+  2. <observable action>
+Expected output: <artifact path or verification result>
+```
+
+After work completes or pauses:
+
+```
+Step result
+Progress: <pct>% (<done> of <total> steps complete; current step <n> of <total>)
+Tier: <tier-number> <tier-label>
+Step: <sub-step-label>
+Result: <done | blocked | failed | skipped | imported>
+What happened:
+  1. <observable action completed>
+  2. <artifact or verification result>
+Next: <next command or pause question>
+```
+
 ## Pause Format (relay from orchestrator)
 
 ```

package/skills/god-next.md

@@ -147,6 +147,17 @@ Display: "Suggested next: /god-arch
           Why: PRD is complete; architecture is the next gate"
 ```
 
+When the suggestion is based on state.json, also show the immediate route:
+
+```
+Path ahead:
+  1. Current: <tier>/<substep> - <status>
+  2. Next: /god-X - <why>
+  3. Then: /god-Y - <next gate, if known>
+```
+
+Keep the route to 3 lines unless the user asks for the full plan.
+
 ## Process for Mode 4 (intent-based)
 
 ```
@@ -280,10 +291,16 @@ recommending archaeology, reconstruction, arc-ready, pillars, or refactor work.
 Godpowers Next
 
 Current state: [where we are]
+Progress: [pct]% ([done] of [total] steps complete; current step [n] of [total])
 Suggested next: [/god-X]
 
 Why: [one-line reason]
 
+Path ahead:
+  1. Current: [tier/substep] - [status]
+  2. Next: [/god-X] - [why]
+  3. Then: [/god-Y or "recompute after gate"]
+
 [If prereqs missing]:
 Pre-flight: missing [prereq]
 Auto-complete available: /god-Y

package/skills/god-status.md

@@ -33,6 +33,9 @@ Re-derive state from disk. Your memory is not authoritative. The file system is.
    - If artifact exists but PROGRESS.md says "pending": FLAG as untracked work
 6. Report:
    - Current mode and scale
+   - Progress summary: percentage, completed step count, current step number
+   - What happened recently, using CHECKPOINT.md actions when available
+   - What happens next, using routing and disk state
    - Per-tier status (with disk verification)
    - Any inconsistencies between PROGRESS.md and disk
    - Suggested next action
@@ -45,6 +48,17 @@ Godpowers Status
 
 Mode: A (greenfield)    Scale: medium
 Started: 2026-05-09
+Progress: 15% (2 of 13 steps complete; current step 3 of 13)
+Current: Tier 1 Planning / Architecture
+
+What happened recently:
+  1. PRD artifact verified on disk
+  2. Tier state refreshed from state.json
+
+What happens next:
+  1. Run /god-arch
+  2. Verify architecture artifact
+  3. Recompute next gate with /god-next
 
 Tier 1: Planning
   + PRD           done     .godpowers/prd/PRD.md (lint clean: 0 errors)

package/skills/god-suite-init.md

@@ -32,12 +32,23 @@ are listed manually; godpowers does NOT auto-walk parent dirs.
    - Byte-identical files to track (one per line; e.g., LICENSE, .editorconfig)
    - Version-table entries (optional; can be added later)
    - Shared standards (node-version, linter; optional)
-3. Spawn `god-coordinator` agent in `init` mode with collected inputs.
-4. god-coordinator writes `.godpowers/suite-config.yaml` and updates
+3. Create `.godpowers/runs/<run-id>/COORDINATOR-HANDOFF.md` with the
+   collected suite name, sibling paths, byte-identical files, version-table
+   entries, shared standards, and init-mode instruction.
+4. Spawn `god-coordinator` agent in `init` mode with only a display-safe
+   payload:
+   - Name the hub path.
+   - Name the operation as `init`.
+   - Name the handoff file path.
+   - Say: "Read the handoff file first, then perform suite init from disk
+     state. Return only user-facing progress and final status."
+   Do not put sibling paths, version-table entries, shared standards, local
+   file lists, or detailed instructions in the visible spawn message.
+5. god-coordinator writes `.godpowers/suite-config.yaml` and updates
    each sibling's state.json with `suite.hubPath`.
-5. Initial `lib/suite-state.refreshFromRepos` runs to populate
+6. Initial `lib/suite-state.refreshFromRepos` runs to populate
    `.godpowers/suite/state.json` and `STATE.md`.
-6. Report registration complete; suggest `/god-suite-status` next.
+7. Report registration complete; suggest `/god-suite-status` next.
 
 ## Output
 

package/skills/god-suite-patch.md

@@ -22,11 +22,23 @@ locally; the coordinator tracks atomicity.
    - Patch description (what's the change)
    - Repos in scope (defaults: all siblings; user can subset)
    - Per-repo any specific notes
-3. Spawn `god-coordinator` in `patch` mode.
-4. For each repo in scope:
-   - Spawn that repo's `god-orchestrator` with the patch directive
+3. Create `.godpowers/runs/<run-id>/COORDINATOR-HANDOFF.md` with the patch
+   description, repos in scope, per-repo notes, dry-run flag, and patch-mode
+   instruction.
+4. Spawn `god-coordinator` in `patch` mode with only a display-safe payload:
+   - Name the hub path.
+   - Name the operation as `patch`.
+   - Name the handoff file path.
+   - Say: "Read the handoff file first, then coordinate the suite patch from
+     disk state. Return only user-facing progress and final status."
+   Do not put patch descriptions, per-repo notes, sibling paths, local file
+   lists, or detailed instructions in the visible spawn message.
+5. For each repo in scope:
+   - Write a per-repo orchestrator handoff file and spawn that repo's
+     `god-orchestrator` with only a display-safe pointer for the patch
+     directive
    - Track success/failure
-5. Coordinator aggregates results:
+6. Coordinator aggregates results:
    - All succeeded: report success; append to SYNC-LOG.md
    - Some failed: report partial; suggest manual continuation OR
      rollback (`/god-suite-patch --rollback <patch-id>`)

package/skills/god-suite-release.md

@@ -17,15 +17,27 @@ A version bump that knows about dependents. Different from `/god-launch`
 
 1. Verify suite is registered.
 2. Prompt for: which repo, new version, release notes.
-3. Spawn `god-coordinator` in `release` mode.
-4. god-coordinator:
+3. Create `.godpowers/runs/<run-id>/COORDINATOR-HANDOFF.md` with the repo,
+   new version, release notes, propagation flags, and suite release
+   instruction.
+4. Spawn `god-coordinator` in `release` mode with only a display-safe
+   payload:
+   - Name the hub path.
+   - Name the operation as `release`.
+   - Name the handoff file path.
+   - Say: "Read the handoff file first, then coordinate the suite release
+     from disk state. Return only user-facing progress and final status."
+   Do not put release notes, dependency impact, sibling paths, local file
+   lists, or detailed instructions in the visible spawn message.
+5. god-coordinator:
    - Scans suite version-table for repos that depend on the bumped repo
-   - For each dependent: spawns its `god-orchestrator` with a
+   - For each dependent: writes a per-repo orchestrator handoff file and
+     spawns its `god-orchestrator` with only a display-safe pointer for the
      `version-bump` directive (NOT a full arc)
    - Aggregates results per-repo
    - Updates `.godpowers/suite-config.yaml` version-table to match
    - Appends to `.godpowers/suite/SYNC-LOG.md`
-5. Reports aggregated outcome (bumped + propagated repos).
+6. Reports aggregated outcome (bumped + propagated repos).
 
 ## Forms
 

package/skills/god-version.md

@@ -14,7 +14,7 @@ Print version and a short capability summary.
 ## Output
 
 ```
-Godpowers v1.6.5
+Godpowers v1.6.6
 Install: /Users/.../.claude/  (matches package.json)
 Surface: 106 skills, 39 agents, 13 workflows, 36 recipes
 Schema: intent.v1, state.v1, events.v1, workflow.v1, routing.v1, recipe.v1

package/templates/PROGRESS.md

@@ -7,11 +7,33 @@ Mode: [A: greenfield | B: gap-fill | C: audit | D: multi-repo]
 Scale: [trivial | small | medium | large | enterprise]
 Started: [ISO 8601 timestamp]
 Last updated: [ISO 8601 timestamp]
+Progress: [0-100]% ([completed] of [total] steps complete; current step [n] of [total])
+Current: [Tier N label] / [sub-step label]
 
 ## Project Description
 
 [One paragraph from /god-init]
 
+## Current Step
+
+Why this now: [One sentence tied to disk state or the prior gate]
+
+What will happen:
+1. [Observable action]
+2. [Observable action]
+3. [Observable action, if needed]
+
+Expected output: [Artifact path or verification result]
+
+## Recent Step Results
+
+What happened:
+1. [Observable action completed]
+2. [Artifact or state update]
+3. [Verification result]
+
+Next: [Next command or pause question]
+
 ## Tier Status
 
 | Tier | Sub-step | Status | Artifact | Updated |