godpowers 1.6.6 → 1.6.8

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,70 @@ 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.8] - 2026-05-16
+
+Staging deferral patch. Keeps Godpowers moving through local and CI-verifiable
+shipping work instead of pausing early for a deployed staging URL.
+
+### Changed
+- `god-orchestrator` now treats deployed staging verification as deferred by
+  default when no live target URL is evidenced and the user did not request
+  staging.
+- `/god-mode`, `/god-deploy`, and `/god-launch` now ask for
+  `STAGING_APP_URL` only when the user explicitly requests staging, invokes
+  deployed verification, or reaches final project sign-off.
+- Deploy, observe, and launch specialists now record missing deployed access in
+  `.godpowers/deploy/WAITING-FOR-EXTERNAL-ACCESS.md` while continuing through
+  local and CI-verifiable gates.
+
+### Guardrails
+- Godpowers still never invents staging or production domains from names,
+  brands, titles, or common TLDs.
+- Provider keys, dashboards, DNS tokens, production secrets, and admin consoles
+  are requested only after a named scripted check proves that exact access is
+  needed.
+- Final sign-off can still run deployed smoke immediately when the user
+  provides `STAGING_APP_URL=<deployed staging origin>`.
+
+## [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.8-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,9 @@ 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.8 keeps the stable Godpowers surface while making shipping less
+interruptive: deployed staging verification is deferred until you request
+staging, run deployed verification, or reach final project sign-off.
 
 It fuses four disciplines into one unified workflow:
 

package/RELEASE.md

@@ -1,11 +1,11 @@
-# Godpowers 1.6.6 Release
+# Godpowers 1.6.8 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.8 keeps shipping work moving when a deployed staging URL is not
+ready yet. The goal of this patch is to finish local and CI-verifiable deploy,
+observe, harden, and launch gates first, then ask for `STAGING_APP_URL` only
+when the user requests staging or reaches final sign-off.
 
 ## What is stable
 
@@ -27,29 +27,31 @@ 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.
+- `god-orchestrator` now documents staging URL deferral as the default shipping
+  closure policy.
+- `/god-mode`, `/god-deploy`, and `/god-launch` now continue through local and
+  CI-verifiable gates when no live deployed origin is evidenced.
+- `god-deploy-engineer`, `god-observability-engineer`, and
+  `god-launch-strategist` now treat missing deployed staging as deferred unless
+  the user explicitly requested staging.
+- Missing deployed access is recorded in
+  `.godpowers/deploy/WAITING-FOR-EXTERNAL-ACCESS.md` with the exact command to
+  run later.
+- At final sign-off, Godpowers offers three clear choices: provide
+  `STAGING_APP_URL=<deployed staging origin>`, sign off local-only with
+  deployed verification deferred, or run `/god-deploy --stage` later.
+
+## What 1.6.8 means
+
+Godpowers 1.6.8 does not expand the public command surface. It changes when
+staging access is requested: not during ordinary mid-arc progress, but at an
+explicit staging request, deployed verification command, or final project
+sign-off.
+
+The release keeps the no-guessed-domain rule intact. Godpowers must not invent
+a staging URL from a product name, brand name, README title, or common TLD.
+If only local URLs exist, it runs local smoke, records deployed verification as
+deferred, and continues.
 
 Safe sync and unresolved Critical harden findings remain release-truth gates.
 Per-repo Quarterback ownership remains intact for Mode D suite work.
@@ -59,8 +61,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.8` git tag points to the release commit that matches the npm
+`godpowers@1.6.8` 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-deploy-engineer.md

@@ -65,11 +65,16 @@ Build is complete. All tests pass. `.godpowers/build/STATE.md` shows green.
   only when needed by the next command, exact provider links only when a failed
   check proves they are needed, and the command Godpowers will run after access
   exists.
-- Default first pause: ask only for `STAGING_APP_URL=<staging-origin>` so the
-  real smoke command can run. Do not ask for provider keys, API tokens,
-  dashboards, DNS tokens, production secrets, admin consoles, or test users
-  until a named deploy, smoke, rollback, health, callback, webhook, export, or
-  observability check cannot run without that exact item.
+- Default behavior: do not pause mid-arc only to ask for
+  `STAGING_APP_URL=<staging-origin>`. Record deployed staging as deferred, keep
+  the exact smoke command in the waiting artifact, and continue through local
+  and CI-verifiable deploy readiness.
+- Ask for `STAGING_APP_URL` only when the user explicitly requested deployed
+  staging, invokes `/god-deploy` for deployed verification, or reaches final
+  project sign-off. Do not ask for provider keys, API tokens, dashboards, DNS
+  tokens, production secrets, admin consoles, or test users until a named
+  deploy, smoke, rollback, health, callback, webhook, export, or observability
+  check cannot run without that exact item.
 - Treat a staging or production origin as known only when it appears in direct
   evidence: current user input, env/config values, deployment config, CI
   variable references, IaC output, hosting CLI output, or deployment docs that
@@ -122,6 +127,6 @@ Write `.godpowers/deploy/STATE.md`:
 - Paper canary (label without traffic split)
 - Broad provider checklist with no scripts or exact access bundle
 - Marks deploy done when the only verified target is missing
-- Requests all provider keys before the staging URL smoke check has run
+- Requests provider keys before an exact scripted check proves they are needed
 - Invents or guesses a staging or production domain
 - Treats production as staging without explicit user approval

package/agents/god-launch-strategist.md

@@ -71,7 +71,8 @@ For each channel:
   `.godpowers/observe/STATE.md`.
 - If deploy or observe is waiting on external access, do not create a broad
   dashboard checklist. Reference only the smallest next access item from the
-  waiting bundle and write launch state as `waiting-for-external-access`.
+  waiting bundle and write launch state as local-ready with deployed
+  verification deferred unless the user explicitly requested staging now.
 - If a staging or production URL is available, run or specify the exact smoke
   command and record the result.
 - If only local staging is available, run local launch-readiness checks and
@@ -85,7 +86,10 @@ For each channel:
   current. Never infer a launch URL from product name, repo name, package name,
   README title, brand name, or common TLDs.
 - If only production is known, do not treat it as staging. If no deployed
-  origin is known, pause for `STAGING_APP_URL=<deployed staging origin>`.
+  origin is known, do not pause mid-arc for the staging URL. Record deployed
+  launch verification as deferred and ask for
+  `STAGING_APP_URL=<deployed staging origin>` only when the user requests
+  staging or final project sign-off begins.
 
 ## Output
 

package/agents/god-observability-engineer.md

@@ -17,7 +17,8 @@ Wire observability.
 
 `.godpowers/deploy/STATE.md` exists. App is deployed and reachable, or deploy
 state documents a tested local staging harness plus a single external access
-bundle.
+bundle. A deferred staging URL must not block observability setup when local or
+CI-verifiable checks can still run.
 
 ## Process
 
@@ -69,7 +70,9 @@ For each PRD success metric, define an SLO:
   Prefer local definitions as code, runbook dry-runs, log-shape checks, and CI
   verification first.
 - If a credential is truly required, append one exact access item to the single
-  waiting access bundle, with the command that will run next.
+  waiting access bundle, with the command that will run next. Do not pause
+  mid-arc just to request the deployed staging origin unless the user has
+  explicitly asked to stage now.
 - Under `/god-mode --yolo`, continue through every local or CI-verifiable
   observability check before pausing for external access.
 

package/agents/god-orchestrator.md

@@ -382,6 +382,14 @@ The shipping tier must not end by listing a broad provider checklist. God Mode
 either ships, creates the automation needed to ship, or pauses on one precise
 external access bundle.
 
+Default behavior: do not pause mid-arc just to ask for a staging URL. If the
+user has not explicitly requested deployed staging verification and no live
+target URL is evidenced, complete every local and CI-verifiable shipping gate,
+write the missing deployed-origin item to
+`.godpowers/deploy/WAITING-FOR-EXTERNAL-ACCESS.md`, and continue. Ask for
+`STAGING_APP_URL` only when the user requests staging, invokes `/god-deploy`
+or `/god-launch` for deployed verification, or reaches final project sign-off.
+
 For deploy, observe, harden, and launch:
 1. Detect the target environment from deploy config, org context, env files,
    CI config, README, existing scripts, and provider CLIs.
@@ -399,29 +407,41 @@ For deploy, observe, harden, and launch:
      access bundle needed
 5. Under `--yolo`, auto-pick safe defaults for provider-neutral choices and
    continue through every local and CI-verifiable gate.
-6. Only pause when real external access is required and absent. The pause must
-   ask for the smallest next input needed to run the next concrete check. The
-   first pause should usually ask only for the deployed staging origin, for
-   example `STAGING_APP_URL=<staging-origin>`. Do not ask for API keys,
-   provider dashboards, DNS tokens, production secrets, or admin consoles until
-   a specific scripted check cannot run without that exact access.
-7. Do not say "Suggested next" for a blocked shipping tier. Say either
-   `Arc complete` or `PAUSE: external access required`, with the exact artifact
-   that lists the required bundle.
+6. If deployed verification is deferred by default, mark the shipping artifact
+   as local/CI ready and continue. Do not pause for `STAGING_APP_URL` yet.
+7. Only pause when the user explicitly requested deployed staging or final
+   sign-off requires a real deployed check. The pause must ask for the smallest
+   next input needed to run the next concrete check. The first external pause
+   should usually ask only for the deployed staging origin, for example
+   `STAGING_APP_URL=<staging-origin>`. Do not ask for API keys, provider
+   dashboards, DNS tokens, production secrets, or admin consoles until a
+   specific scripted check cannot run without that exact access.
+8. At final sign-off, if deployed verification is still deferred, present:
+   "Local and CI-verifiable closure is complete. Provide
+   `STAGING_APP_URL=<deployed staging origin>` to run deployed smoke now, say
+   `sign off local-only` to finish with deployed verification deferred, or run
+   `/god-deploy --stage` later."
+9. Do not say "Suggested next" for a blocked shipping tier. Say either
+   `Arc complete`, `Arc complete with deployed verification deferred`, or
+   `PAUSE: external access required`, with the exact artifact that lists the
+   required bundle.
 
 ### External Access Ladder
 
 Use this order when external access is missing:
 
-1. Ask for the deployed staging origin only if no live target URL is known from
-   explicit evidence.
-2. Run the real staging smoke command against that origin.
-3. Ask for a provider key, dashboard, admin console, or test user only when a
+1. If no live target URL is known from explicit evidence, defer the deployed
+   staging origin request unless the user asked to stage now or the arc has
+   reached final sign-off.
+2. When staging is requested or final sign-off begins, ask for the deployed
+   staging origin only.
+3. Run the real staging smoke command against that origin.
+4. Ask for a provider key, dashboard, admin console, or test user only when a
    named smoke, callback, webhook, export, observability, or rollback check
    fails or cannot execute without that exact item.
-4. Add at most one new access item per pause unless several items are required
+5. Add at most one new access item per pause unless several items are required
    by the same command invocation.
-5. Every access request must include the command that will run next and the
+6. Every access request must include the command that will run next and the
    artifact that will be updated after it runs.
 
 Never request every possible key or API at the start of shipping. Keys and API
@@ -441,8 +461,10 @@ evidence:
 Never invent domains from the product name, package name, repo name, README
 title, brand name, or common TLDs. Never turn `scriven` into
 `https://scriven.app`, or any similar guessed URL. If only production is known,
-do not call it staging. If only local URLs exist, run local smoke only and pause
-for `STAGING_APP_URL=<deployed staging origin>` before deployed staging smoke.
+do not call it staging. If only local URLs exist, run local smoke only, record
+deployed staging as deferred, and ask for
+`STAGING_APP_URL=<deployed staging origin>` only when staging is explicitly
+requested or final sign-off begins.
 
 ## YOLO Behavior with Design + Linkage
 
@@ -470,13 +492,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 +730,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
@@ -721,8 +748,53 @@ Hide:
 
 When a private rule affects a pause, translate it into the smallest
 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.
+`STAGING_APP_URL=<deployed staging origin>` at final sign-off 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
 

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.8",
   "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-deploy.md

@@ -27,11 +27,12 @@ After god-deploy-engineer returns:
    - real staging or production target tested
    - local staging harness tested with equivalent health, smoke, and rollback
      commands
-   - paused on `.godpowers/deploy/WAITING-FOR-EXTERNAL-ACCESS.md` with one
-     exact missing access bundle
-4. Update `.godpowers/PROGRESS.md`: Deploy status = done only for a tested real
-   target or tested local staging harness. If external access is missing, mark
-   Deploy = waiting-for-external-access, not done.
+   - local/CI deploy readiness complete with deployed staging verification
+     deferred in `.godpowers/deploy/WAITING-FOR-EXTERNAL-ACCESS.md`
+4. Update `.godpowers/PROGRESS.md`: Deploy status can be done when a tested
+   real target or tested local staging harness exists. If deployed staging is
+   deferred, annotate Deploy as done-local with the waiting artifact path and
+   do not pause unless the user explicitly requested staging.
 
 ## On Completion
 
@@ -44,11 +45,14 @@ Suggested next: /god-observe (wire SLOs, alerts, runbooks)
 Under `/god-mode --yolo`, do not stop with a provider checklist. Create or
 update the deploy scripts, smoke command, rollback command, health endpoints,
 env manifest, and local staging harness first. If real external access is still
-required, pause on the single access bundle in
-`.godpowers/deploy/WAITING-FOR-EXTERNAL-ACCESS.md`.
-
-The single access bundle must be incremental. Ask for the smallest next item
-needed to run the next command. If no live target URL is known, ask only for
+required, record the single access bundle in
+`.godpowers/deploy/WAITING-FOR-EXTERNAL-ACCESS.md` and continue until the user
+requests staging or final sign-off begins.
+
+The single access bundle must be incremental. Do not ask for
+`STAGING_APP_URL` mid-arc unless the user requested deployed staging. At final
+sign-off or explicit staging, ask for the smallest next item needed to run the
+next command. If no live target URL is known, ask only for
 `STAGING_APP_URL=<staging-origin>` and the exact smoke command that will run.
 Do not ask for provider keys, API tokens, dashboards, DNS tokens, production
 secrets, admin consoles, or test users until a specific scripted check proves
@@ -59,8 +63,8 @@ values, deployment config, CI variable references, IaC output, hosting CLI
 output, or deployment docs that explicitly label the URL as owned and current.
 Never invent a domain from the product name, repo name, package name, README
 title, brand name, or common TLDs. If only local URLs exist, run local smoke
-only and pause for `STAGING_APP_URL=<deployed staging origin>`. If only
-production is known, do not use it as staging without explicit user approval.
+only, record deployed staging as deferred, and continue. If only production is
+known, do not use it as staging without explicit user approval.
 
 
 ## Re-invocation contract

package/skills/god-launch.md

@@ -52,12 +52,15 @@ Or: /god-status (see the final state)
 Under `/god-mode --yolo`, do not stop by listing provider dashboards. Create
 the launch runbook, smoke command, source attribution plan, and local
 launch-readiness checks. If real launch is blocked by missing external access,
-pause on the single access bundle from deploy or launch state.
+record the single access bundle from deploy or launch state and continue until
+the user requests staging or final sign-off begins.
 
 The launch pause must not expand into every possible channel, analytics, or
 provider credential. Ask only for the next missing access item needed to run a
-named live smoke, launch-readiness, attribution, or monitoring check. If no
-live target URL is known, ask only for `STAGING_APP_URL=<staging-origin>`.
+named live smoke, launch-readiness, attribution, or monitoring check. Do not
+ask mid-arc for `STAGING_APP_URL` unless the user requested deployed staging.
+At final sign-off, if no live target URL is known, ask only for
+`STAGING_APP_URL=<staging-origin>`.
 
 Live target URLs must be evidence-backed. Never invent a domain from the
 product name, repo name, package name, README title, brand name, or common TLDs.

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

@@ -94,18 +94,20 @@ You are receiving a /god-mode invocation. Your job is to spawn the
        security or a genuine human-only decision.
      - Instruction that deploy, observe, harden, and launch must follow the
        Shipping Closure Protocol: verify a real environment when available,
-       otherwise create local/CI-verifiable deploy automation and pause only
-       for one exact external access bundle.
+       otherwise create local/CI-verifiable deploy automation, defer deployed
+       staging by default, and continue until the user requests staging or the
+       arc reaches final sign-off.
      - Instruction that keys, API tokens, dashboards, admin consoles, and
-       provider-specific access are last-mile inputs. The first external pause
-       should ask only for the smallest next item needed by a concrete command,
-       usually `STAGING_APP_URL=<staging-origin>`. Ask for additional provider
-       access only after a named check proves it is needed.
+       provider-specific access are last-mile inputs. Do not pause mid-arc for
+       `STAGING_APP_URL` unless the user requested deployed staging. At final
+       sign-off, ask only for the smallest next item needed by a concrete
+       command, usually `STAGING_APP_URL=<staging-origin>`. Ask for additional
+       provider access only after a named check proves it is needed.
      - Instruction that staging, preview, and production URLs must come from
        direct evidence. Never infer or invent a domain from project name,
        package name, repo name, README title, or brand name. If no deployed
-       origin is evidenced, pause for
-       `STAGING_APP_URL=<deployed staging origin>`.
+       origin is evidenced, record deployed staging as deferred and continue
+       until staging is requested or final sign-off begins.
      - Instruction that brownfield and bluefield greenfield simulation audits
        must be acted on by god-greenfieldifier. The greenfieldifier writes
        `.godpowers/audit/GREENFIELDIFY-PLAN.md`, pauses before risky canonical
@@ -164,6 +166,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
@@ -179,8 +183,41 @@ Hide:
 
 If an internal instruction must influence a pause, translate it into the
 smallest user-facing question. For example, ask for
-`STAGING_APP_URL=<deployed staging origin>` instead of exposing the full
-Shipping Closure Protocol.
+`STAGING_APP_URL=<deployed staging origin>` at final sign-off 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 |