godpowers 1.6.6 → 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,45 @@ 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

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.6-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.6 keeps the stable Godpowers surface while making more Codex
-orchestrator spawns transcript-safe: `/god-mode`, `/god-init`, and Mode D
-suite coordinator paths now use private handoff files with small display-safe
-pointers. 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.6 Release
+# Godpowers 1.6.7 Release
 
 Date: 2026-05-16
 
-Godpowers 1.6.6 extends transcript-safe spawn handling beyond `/god-mode`.
-The goal of this patch is to keep Codex-visible spawn messages small and safe
-for `/god-init` and Mode D suite coordination while preserving the same
-orchestrator and coordinator behavior.
+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,29 +26,36 @@ orchestrator and coordinator behavior.
 
 ## What is new
 
-- `/god-init` now writes detailed initialization context to
-  `.godpowers/runs/<run-id>/INIT-ORCHESTRATOR-HANDOFF.md` before spawning
-  `god-orchestrator`.
-- `/god-suite-init`, `/god-suite-release`, and `/god-suite-patch` now write
-  suite coordination context to
-  `.godpowers/runs/<run-id>/COORDINATOR-HANDOFF.md` before spawning
-  `god-coordinator`.
-- `god-coordinator` now writes per-repo orchestrator context to
-  `.godpowers/runs/<run-id>/COORDINATOR-ORCHESTRATOR-HANDOFF.md` before
-  spawning a target repo's `god-orchestrator`.
-- `god-orchestrator` now treats handoff files as a general caller protocol,
-  not only as a `/god-mode` protocol.
-- `/god-hygiene` routing no longer lists `god-orchestrator` as a secondary
-  spawn because the skill only runs artifact, dependency, and documentation
-  audits.
-
-## What 1.6.6 means
-
-Godpowers 1.6.6 does not expand the public command surface. It fixes more
-Codex spawn integration paths so the right agent is still started, but the host
-UI only sees a small pointer to disk state instead of raw project description,
-suite metadata, release notes, patch directives, dependency graphs, routing
-rules, or 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.
 Per-repo Quarterback ownership remains intact for Mode D suite work.
@@ -59,8 +65,8 @@ Per-repo Quarterback ownership remains intact for Mode D suite work.
 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.6` git tag points to the release commit that matches the npm
-`godpowers@1.6.6` 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-orchestrator.md

@@ -470,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
@@ -705,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
@@ -724,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.6",
+  "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/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/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 |