@tekyzinc/gsd-t 2.24.7 → 2.28.12

package/commands/gsd-t-health.md

@@ -0,0 +1,138 @@
+# GSD-T: Health — Validate Project Structure
+
+You are diagnosing the health of a GSD-T project. Check every required file and directory, report findings, and optionally repair missing pieces.
+
+## Step 0: Launch via Subagent (default)
+
+When invoked directly by the user, spawn yourself as a Task subagent for a fresh context window:
+
+```
+Task subagent (general-purpose, model: haiku):
+"Run the GSD-T health check. Read commands/gsd-t-health.md for your full instructions.
+Arguments: {$ARGUMENTS}
+Skip Step 0 — you are already the subagent."
+```
+
+Return the subagent's output and stop. Only skip Step 0 if you are already running as a subagent.
+
+## Step 1: Determine Mode
+
+If `--repair` appears in $ARGUMENTS, set `REPAIR=true`. Otherwise `REPAIR=false`.
+
+## Step 2: Check Required Structure
+
+Check each item below. Record status as `OK`, `MISSING`, or `INVALID`.
+
+### Root files
+| File | Check |
+|------|-------|
+| `CLAUDE.md` | Exists and non-empty |
+| `README.md` | Exists and non-empty |
+| `.gsd-t/progress.md` | Exists, has `## Status:` and `## Version:` sections |
+| `.gsd-t/backlog.md` | Exists |
+| `.gsd-t/backlog-settings.md` | Exists |
+
+### Required directories
+| Directory | Check |
+|-----------|-------|
+| `.gsd-t/contracts/` | Exists |
+| `.gsd-t/domains/` | Exists |
+| `docs/` | Exists |
+
+### Docs
+| File | Check |
+|------|-------|
+| `docs/requirements.md` | Exists |
+| `docs/architecture.md` | Exists |
+| `docs/workflows.md` | Exists |
+| `docs/infrastructure.md` | Exists |
+
+### Active milestone (if any)
+Read `.gsd-t/progress.md` to find active milestone. For each domain listed as active:
+- `.gsd-t/domains/{domain}/scope.md` — exists?
+- `.gsd-t/domains/{domain}/tasks.md` — exists?
+- `.gsd-t/contracts/` — at least one `.md` contract file present?
+
+## Step 3: Additional Checks
+
+1. **Version consistency**: Read `## Version:` from `.gsd-t/progress.md`. If `package.json` exists, compare — they should match.
+2. **Status validity**: Read `## Status:` value. Confirm it's one of: `DEFINED`, `PARTITIONED`, `DISCUSSED`, `PLANNED`, `EXECUTED`, `SYNCED`, `INTEGRATED`, `VERIFIED`, `VERIFIED-WITH-WARNINGS`, `VERIFY-FAILED`, `COMPLETED`.
+3. **Decision Log**: Confirm `## Decision Log` section exists and has at least one entry.
+4. **Contract integrity**: For each `.md` file in `.gsd-t/contracts/`, confirm it's non-empty.
+5. **Domain integrity**: For each directory in `.gsd-t/domains/`, confirm at least `scope.md` exists.
+
+## Step 4: Report Findings
+
+Output a health report in this format:
+
+```
+GSD-T Health Report
+═══════════════════════════════════════════════════════════
+
+Core Files
+  ✓ CLAUDE.md
+  ✓ README.md
+  ✗ .gsd-t/progress.md — MISSING
+  ✓ .gsd-t/backlog.md
+
+Directories
+  ✓ .gsd-t/contracts/
+  ✗ docs/ — MISSING
+
+Docs
+  ✓ docs/requirements.md
+  ✗ docs/architecture.md — MISSING
+
+Active Milestone: {name | none}
+  ✓ .gsd-t/domains/{domain}/scope.md
+  ✗ .gsd-t/domains/{domain}/tasks.md — MISSING
+
+Additional Checks
+  ✓ Version: 2.27.10 (consistent with package.json)
+  ✓ Status: PLANNED (valid)
+  ✓ Decision Log: present
+  ✗ contracts/api-contract.md — EMPTY
+
+═══════════════════════════════════════════════════════════
+Summary: {N} OK  |  {N} missing  |  {N} invalid
+Overall: {HEALTHY | DEGRADED | BROKEN}
+```
+
+Status thresholds:
+- **HEALTHY**: 0 missing, 0 invalid
+- **DEGRADED**: 1-3 missing/invalid (non-critical)
+- **BROKEN**: 4+ missing/invalid OR progress.md missing OR contracts/ missing
+
+## Step 5: Repair (if --repair)
+
+If `REPAIR=true` and any items are MISSING (not INVALID), create them now:
+
+| Missing item | Repair action |
+|--------------|---------------|
+| `CLAUDE.md` | Create from `templates/CLAUDE-project.md` (with `{Project Name}` = directory name) |
+| `README.md` | Create minimal `# {Project Name}\n\n_No description yet._\n` |
+| `.gsd-t/progress.md` | Create from `templates/progress.md` |
+| `.gsd-t/backlog.md` | Create from `templates/backlog.md` |
+| `.gsd-t/backlog-settings.md` | Create from `templates/backlog-settings.md` |
+| `.gsd-t/contracts/` | Create empty directory |
+| `.gsd-t/domains/` | Create empty directory |
+| `docs/` | Create directory |
+| `docs/requirements.md` | Create from `templates/requirements.md` |
+| `docs/architecture.md` | Create from `templates/architecture.md` |
+| `docs/workflows.md` | Create from `templates/workflows.md` |
+| `docs/infrastructure.md` | Create from `templates/infrastructure.md` |
+| Domain `scope.md` | Create minimal scope with domain name as heading |
+| Domain `tasks.md` | Create minimal task list with `## Tasks\n_No tasks defined yet._` |
+
+After repair, re-run the checks and report the final state.
+
+**Do NOT repair INVALID items** (e.g., empty contracts, bad status values) — flag them for user action.
+
+## Step 6: Next Steps
+
+If HEALTHY → "✅ GSD-T structure is healthy — all required files present."
+If DEGRADED with --repair done → "✅ Repaired {N} missing files. Run /user:gsd-t-health again to confirm."
+If DEGRADED without --repair → "⚠ Run /user:gsd-t-health --repair to create {N} missing files."
+If BROKEN → "🔴 Project structure is broken. Run /user:gsd-t-health --repair or /user:gsd-t-init to rebuild."
+
+$ARGUMENTS

package/commands/gsd-t-help.md

@@ -51,6 +51,8 @@ UTILITIES                                                              Manual
   resume              Restore context after break
   quick               Fast task with GSD-T guarantees
   debug               Systematic debugging with state
+  health              Validate .gsd-t/ structure, optionally repair missing files
+  pause               Save exact position for reliable resume later
   promote-debt        Convert techdebt items to milestones
   populate            Auto-populate docs from existing codebase
   log                 Sync progress Decision Log with recent git activity

package/commands/gsd-t-init-scan-setup.md

@@ -39,15 +39,38 @@ All subsequent steps run from inside the project directory.
 
 Execute the full init workflow (same as `/user:gsd-t-init`):
 
-1. Create `.gsd-t/` directory structure (contracts/, domains/, progress.md, backlog.md, backlog-settings.md)
+1. Create `.gsd-t/` directory structure (contracts/, domains/, progress.md, backlog.md, backlog-settings.md, token-log.md, qa-issues.md)
 2. Ensure `CLAUDE.md` exists (create starter if missing, append GSD-T section if present without it)
 3. Create `docs/` with all 4 living document templates (skip existing files)
 4. Ensure `README.md` exists
-5. Map existing codebase if code exists
-6. Initialize backlog with auto-derived categories
-7. Register project in `~/.claude/.gsd-t-projects`
-
-**If `.gsd-t/` already exists**: Skip init — it's already done. Log and continue to scan.
+5. **Copy project settings**:
+   - First, ensure `~/.claude/settings.local` exists. If it does NOT, create it with these defaults:
+     ```json
+     {
+       "permissions": {
+         "allow": [
+           "Edit",
+           "Write",
+           "Bash",
+           "Read",
+           "WebSearch",
+           "WebFetch",
+           "Skill"
+         ]
+       },
+       "outputStyle": "default"
+     }
+     ```
+     Log: "Created ~/.claude/settings.local with default permissions — update the allow list to match your security preferences."
+   - Then, if `.claude/settings.local.json` does NOT already exist in the project root:
+     - Create `.claude/` directory in the project root if needed
+     - Copy `~/.claude/settings.local` → `.claude/settings.local.json`
+   - Skip the copy silently if the target already exists
+6. Map existing codebase if code exists
+7. Initialize backlog with auto-derived categories
+8. Register project in `~/.claude/.gsd-t-projects`
+
+**If `.gsd-t/` already exists**: Skip init — it's already done. Log and continue to scan. Still check and copy settings.local (step 5) even if init is skipped.
 
 ## Step 4: Deep Codebase Scan (gsd-t-scan)
 

package/commands/gsd-t-init.md

@@ -20,11 +20,31 @@ If yes, read `.gsd/` state and create equivalent `.gsd-t/` structure.
 
 ## Step 2: Copy Local Settings
 
-If `~/.claude/settings.local` exists and `.claude/settings.local.json` does not exist in the project:
-1. Create the `.claude/` directory in the project root if it doesn't exist
-2. Copy `~/.claude/settings.local` → `.claude/settings.local.json`
-
-Skip silently if the source file doesn't exist or the target already exists.
+1. **Ensure `~/.claude/settings.local` exists**:
+   - If it does NOT exist, create it now with these default permissions:
+     ```json
+     {
+       "permissions": {
+         "allow": [
+           "Edit",
+           "Write",
+           "Bash",
+           "Read",
+           "WebSearch",
+           "WebFetch",
+           "Skill"
+         ]
+       },
+       "outputStyle": "default"
+     }
+     ```
+     After creating it, log: "Created ~/.claude/settings.local with default permissions — update the allow list to match your security preferences."
+
+2. **Copy to project**: If `.claude/settings.local.json` does NOT already exist in the project root:
+   - Create the `.claude/` directory in the project root if it doesn't exist
+   - Copy `~/.claude/settings.local` → `.claude/settings.local.json`
+
+Skip the copy (step 2) silently if the target already exists.
 
 ## Step 3: Create Directory Structure
 
@@ -36,7 +56,21 @@ Skip silently if the source file doesn't exist or the target already exists.
 │   └── .gitkeep
 ├── backlog.md
 ├── backlog-settings.md
-└── progress.md
+├── progress.md
+├── token-log.md
+└── qa-issues.md
+```
+
+Create `token-log.md` with header row:
+```
+| Date | Command | Step | Model | Duration(s) | Notes |
+|------|---------|------|-------|-------------|-------|
+```
+
+Create `qa-issues.md` with header row:
+```
+| Date | Command | Step | Model | Duration(s) | Severity | Finding |
+|------|---------|------|-------|-------------|----------|---------|
 ```
 
 ## Step 4: Initialize Backlog

package/commands/gsd-t-integrate.md

@@ -88,17 +88,26 @@ Result: PASS
 Result: PARTIAL — needs pagination contract addition
 ```
 
-## Step 5: Spawn QA Agent
+## Step 5: Contract Compliance Testing
 
-Spawn the QA teammate to verify contract compliance at domain boundaries:
+Spawn a QA subagent via the Task tool to verify contract compliance at all domain boundaries:
 
 ```
-Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
-  Phase context: integrate. Read .gsd-t/contracts/ for all contract definitions.
-  Run contract compliance tests at every domain boundary.
-  Report: boundary-by-boundary test results.
+Task subagent (general-purpose, model: haiku):
+"Run contract compliance tests for this integration. Read .gsd-t/contracts/ for all contract definitions.
+Test every domain boundary: verify that producers and consumers match their contract shapes.
+Run the full test suite.
+Report: boundary-by-boundary test results with pass/fail counts."
 ```
 
+**OBSERVABILITY LOGGING (MANDATORY):**
+Before spawning: run `date +%s` via Bash → save as START
+After subagent returns: run `date +%s` → compute `DURATION=$((END-START))`
+Append to `.gsd-t/token-log.md` (create with header `| Date | Command | Step | Model | Duration(s) | Notes |` if missing):
+`| {YYYY-MM-DD HH:MM} | gsd-t-integrate | Step 5 | haiku | {DURATION}s | {pass/fail}, {N} boundaries tested |`
+If QA found issues, append each to `.gsd-t/qa-issues.md` (create with header `| Date | Command | Step | Model | Duration(s) | Severity | Finding |` if missing):
+`| {YYYY-MM-DD HH:MM} | gsd-t-integrate | Step 5 | haiku | {DURATION}s | {severity} | {finding} |`
+
 QA failure blocks integration completion.
 
 ## Step 6: Document Ripple

package/commands/gsd-t-partition.md

@@ -175,20 +175,7 @@ Before finalizing the partition:
 2. **Verify passing**: If any tests fail, assign them to the appropriate domain as pre-existing issues
 3. **Map tests to domains**: Note which test files belong to which domain — this informs task planning
 
-## Step 7: Spawn QA Agent
-
-After contracts are written, spawn the QA teammate to generate contract test skeletons:
-
-```
-Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
-  Phase context: partition. Read .gsd-t/contracts/ for contract definitions.
-  Generate contract test skeleton files for every contract.
-  Report: number of test files generated and total test cases.
-```
-
-Wait for QA agent to complete before proceeding. QA failure blocks partition completion.
-
-## Step 8: Validate
+## Step 7: Validate
 
 Before finishing, verify:
 - [ ] Every file in `src/` is owned by exactly one domain

package/commands/gsd-t-pause.md

@@ -0,0 +1,78 @@
+# GSD-T: Pause — Save Exact Position for Later Resume
+
+You are capturing the precise current position in an active GSD-T phase so the user can resume later with zero re-orientation overhead.
+
+## Step 1: Gather Current State
+
+Read the following (use whatever is already in context first — only read files if needed):
+
+1. `.gsd-t/progress.md` — milestone name, current status/phase, version
+2. `.gsd-t/domains/*/tasks.md` — identify which tasks are done, in-progress, or pending
+3. Last entry in the Decision Log (from progress.md)
+4. `$ARGUMENTS` — if user provided a note, capture it verbatim
+
+## Step 2: Determine Exact Position
+
+Identify:
+- **Milestone**: current milestone name
+- **Phase**: current phase (PARTITIONED, PLANNED, EXECUTED, etc.)
+- **Domain** (if in execute/test-sync): which domain was being worked on
+- **Task** (if in execute): which task number was in progress or next up
+- **Last completed action**: what was the last thing that finished
+- **Next action**: what should happen first when resuming
+- **Blockers**: any known blockers or open questions
+
+## Step 3: Create Continue-Here File
+
+Generate a timestamp: `{YYYY}-{MM}-{DD}T{HH}{MM}{SS}` (local time, no separators in time part).
+
+Create `.gsd-t/continue-here-{timestamp}.md`:
+
+```markdown
+# Continue Here — {YYYY-MM-DD HH:MM}
+
+## Snapshot
+- **Milestone**: {milestone name}
+- **Phase**: {phase}
+- **Version**: {version from progress.md}
+- **Paused at**: {domain} → Task {N} | Between phases | {other description}
+
+## Last Completed
+{description of the last thing that finished — specific task, commit, or action}
+
+## Next Action
+{exactly what to do first when resuming — specific, actionable}
+
+## Open Items
+{any known blockers, pending decisions, or things to watch out for}
+{None if clean}
+
+## User Note
+{$ARGUMENTS if provided, otherwise: _No note provided._}
+
+## Resume Command
+/user:gsd-t-resume
+```
+
+## Step 4: Confirm to User
+
+Output:
+
+```
+⏸ Paused: {milestone name} — {phase}
+
+Saved position: .gsd-t/continue-here-{timestamp}.md
+Next action:    {next action summary}
+
+To resume: /user:gsd-t-resume
+```
+
+## Step 5: Do NOT Stop Work (unless user asked to pause all work)
+
+This command only saves position. If the user invoked /pause mid-task intending to stop:
+- They will close the session themselves
+- Do not auto-continue executing tasks after creating the file
+
+If invoked with $ARGUMENTS containing "and continue" or similar, create the file and then continue the current task normally.
+
+$ARGUMENTS

package/commands/gsd-t-plan.md

@@ -12,6 +12,9 @@ Read ALL of these:
 5. `.gsd-t/domains/*/constraints.md` — every domain constraint
 6. `docs/` — requirements, architecture, schema, design
 7. Existing source code (if any) — understand current state
+8. `.gsd-t/CONTEXT.md` (if exists — from discuss phase) — **MANDATORY READ if present**
+
+**If CONTEXT.md exists:** Every Locked Decision listed in it MUST be mapped to at least one task in Step 2. Do NOT proceed to execute if any Locked Decision is unmapped.
 
 ## Step 2: Create Task Lists Per Domain
 
@@ -49,9 +52,25 @@ For each domain, write `.gsd-t/domains/{domain-name}/tasks.md`:
 5. **Ordered**: Tasks within a domain are numbered in execution order
 6. **No implicit knowledge**: Don't assume the executing agent remembers previous tasks — reference contracts and files explicitly
 
+### REQ Traceability
+
+After creating task lists, append a traceability table to `docs/requirements.md`:
+
+```markdown
+## Requirements Traceability (updated by plan phase)
+| REQ-ID | Requirement Summary | Domain | Task(s) | Status |
+|--------|---------------------|--------|---------|--------|
+| REQ-001 | {summary} | {domain} | Task 1, Task 3 | pending |
+| REQ-002 | {summary} | {domain} | Task 2 | pending |
+```
+
+- Every REQ-ID must map to at least one domain/task — orphaned requirements are a planning gap
+- Every task group should trace back to at least one REQ-ID — tasks with no REQ reference may be scope creep
+- Report: orphaned requirements (no task) and unanchored tasks (no REQ)
+
 ## Step 3: Map Cross-Domain Dependencies
 
-Update `.gsd-t/contracts/integration-points.md` with the full dependency graph:
+Update `.gsd-t/contracts/integration-points.md` with the full dependency graph **and wave groupings**:
 
 ```markdown
 # Integration Points
@@ -68,11 +87,37 @@ Update `.gsd-t/contracts/integration-points.md` with the full dependency graph:
 - UNLOCKS: auth Task 3 (user lookup), ui Task 3 (data fetching)
 - VERIFY: Lead confirms schema matches schema-contract.md
 
-### Second Checkpoint  
+### Second Checkpoint
 - GATE: auth Task 4 (auth middleware) must complete
 - UNLOCKS: ui Task 5 (protected routes)
 - VERIFY: Lead confirms auth endpoints match api-contract.md
 
+## Wave Execution Groups
+
+Waves allow parallel execution within a wave and sequential execution between waves.
+Each wave contains domains/tasks that can safely run in parallel (no shared files, no cross-domain dependencies within the wave).
+
+### Wave 1 — Independent (parallel)
+- data-layer: Tasks 1-3
+- auth: Tasks 1-2
+- **Shared files**: NONE — safe to run in parallel
+- **Completes when**: All listed tasks done
+
+### Wave 2 — After Wave 1 Checkpoint (parallel)
+- CHECKPOINT: Lead verifies schema-contract.md before Wave 2 starts
+- auth: Tasks 3-4
+- ui: Tasks 1-2
+- **Shared files**: NONE — safe to run in parallel
+- **Completes when**: All listed tasks done
+
+### Wave 3 — After Wave 2 Checkpoint (sequential)
+- CHECKPOINT: Lead verifies api-contract.md before Wave 3 starts
+- ui: Tasks 3-5
+- **Note**: Sequential — each task depends on the previous
+
+### Integration
+- INTEGRATION: Wire all domains together
+
 ## Execution Order (for solo mode)
 1. data-layer Tasks 1-3
 2. auth Tasks 1-2 (parallel-safe with data-layer)
@@ -84,6 +129,12 @@ Update `.gsd-t/contracts/integration-points.md` with the full dependency graph:
 8. INTEGRATION: wire everything together
 ```
 
+### Wave Grouping Rules:
+1. **Same wave** = no shared files, no dependency between them
+2. **Different wave** = one depends on the other's output, OR they modify the same file
+3. **CHECKPOINT between waves** = lead verifies contract compliance before unlocking next wave
+4. Always check domain `scope.md` files for file ownership — overlapping files → different waves
+
 ## Step 4: Estimate Scope
 
 Add to each domain's `tasks.md`:
@@ -118,18 +169,37 @@ Before finalizing the plan:
 2. **Verify passing**: Document any pre-existing failures — assign them to appropriate domain tasks
 3. **Include test tasks**: Ensure each domain's task list includes test creation/update tasks where acceptance criteria require verification
 
-## Step 7: Spawn QA Agent
+## Step 7: Plan Validation
 
-After task lists are created, spawn the QA teammate to generate acceptance test scenarios:
+Spawn a Task subagent to validate the plan before proceeding:
 
 ```
-Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
-  Phase context: plan. Read .gsd-t/domains/*/tasks.md for task lists.
-  Generate acceptance test scenarios for tasks with user-facing deliverables.
-  Report: number of acceptance test scenarios generated.
+Task subagent (general-purpose, model: haiku):
+"Validate this GSD-T plan. Read:
+- .gsd-t/domains/*/tasks.md (all task lists)
+- .gsd-t/contracts/ (all contracts)
+- docs/requirements.md (including traceability table)
+- .gsd-t/CONTEXT.md (if exists)
+
+Check:
+1. REQ coverage: every REQ-ID in requirements.md maps to at least one task
+2. Locked Decisions (from CONTEXT.md if present): every Locked Decision maps to at least one task
+3. Task completeness: every task has files, contract refs, and acceptance criteria
+4. Cross-domain dependencies: all BLOCKED-BY references point to real tasks
+5. Contract existence: every task referencing a contract has that contract file present
+
+Report: PASS (all checks pass) or FAIL with specific gaps listed."
 ```
 
-Wait for QA agent to complete before proceeding. QA failure blocks plan completion.
+**OBSERVABILITY LOGGING (MANDATORY):**
+Before spawning: run `date +%s` via Bash → save as START
+After subagent returns: run `date +%s` → compute `DURATION=$((END-START))`
+Append to `.gsd-t/token-log.md` (create with header `| Date | Command | Step | Model | Duration(s) | Notes |` if missing):
+`| {YYYY-MM-DD HH:MM} | gsd-t-plan | Step 7 | haiku | {DURATION}s | {PASS/FAIL}, iteration {N} |`
+If validation FAIL, append each gap to `.gsd-t/qa-issues.md` (create with header `| Date | Command | Step | Model | Duration(s) | Severity | Finding |` if missing):
+`| {YYYY-MM-DD HH:MM} | gsd-t-plan | Step 7 | haiku | {DURATION}s | medium | {gap description} |`
+
+**If FAIL**: Fix the identified gaps (up to 3 iterations). If still failing after 3 iterations, STOP and report to user with the specific gaps. Plan cannot proceed until validation PASSES.
 
 ## Step 8: Update Progress
 

package/commands/gsd-t-quick.md

@@ -2,6 +2,23 @@
 
 You are executing a small, focused task that doesn't need full phase planning. This is for bug fixes, config changes, small features, and ad-hoc work.
 
+## Step 0: Launch via Subagent
+
+To give this task a fresh context window and prevent compaction during consecutive quick runs, always execute via a Task subagent.
+
+**If you are the orchestrating agent** (you received the slash command directly):
+Spawn a fresh subagent using the Task tool:
+```
+subagent_type: general-purpose
+prompt: "You are running gsd-t-quick for this request: {$ARGUMENTS}
+Working directory: {current project root}
+Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-quick starting at Step 1."
+```
+Wait for the subagent to complete. Relay its summary to the user. **Do not execute Steps 1–5 yourself.**
+
+**If you are the spawned subagent** (your prompt says "starting at Step 1"):
+Continue to Step 1 below.
+
 ## Step 1: Load Context (Fast)
 
 Read:
@@ -24,20 +41,17 @@ Should I proceed with quick mode or use the full execute workflow?"
 ### If it's within a single domain or pre-partition:
 Proceed.
 
-## Step 3: Spawn QA Agent
-
-Spawn the QA teammate to handle testing for this quick task:
+## Step 3: Execute
 
-```
-Teammate "qa": Read commands/gsd-t-qa.md for your full instructions.
-  Phase context: quick. Read .gsd-t/contracts/ for relevant contracts.
-  Write tests for the change, run the full test suite.
-  Report: test results and any coverage gaps found.
-```
+### Deviation Rules
 
-QA failure blocks the commit.
+When you encounter unexpected situations:
+1. **Bug blocking progress** → Fix it, up to 3 attempts. If still blocked, add to `.gsd-t/deferred-items.md` and skip.
+2. **Missing dependency clearly needed** → Add minimum required code to unblock. Note in commit.
+3. **Blocker (missing file, wrong API)** → Fix blocker and continue. Log if non-trivial.
+4. **Architectural change required** → STOP. Apply Destructive Action Guard. Never self-approve.
 
-## Step 4: Execute
+**3-attempt limit**: Stop looping after 3 failed fix attempts. Log and move on.
 
 1. Identify exactly which files need to change
 2. **Destructive Action Guard**: Check if this task involves destructive or structural changes (DROP TABLE, removing columns, deleting data, replacing architecture patterns, removing working modules, changing schema in ways that conflict with existing data). If YES → STOP and present the change to the user with what exists today, what will change, what will break, and a safe migration path. Wait for explicit approval.
@@ -46,7 +60,7 @@ QA failure blocks the commit.
 5. Verify it works
 6. Commit: `[quick] {description}`
 
-## Step 5: Document Ripple (if GSD-T is active)
+## Step 4: Document Ripple (if GSD-T is active)
 
 If `.gsd-t/progress.md` exists, assess what documentation was affected and update ALL relevant files:
 
@@ -65,7 +79,7 @@ If `.gsd-t/progress.md` exists, assess what documentation was affected and updat
 
 ### Skip what's not affected — most quick tasks will only touch 1-2 of these.
 
-## Step 6: Test & Verify (MANDATORY)
+## Step 5: Test & Verify (MANDATORY)
 
 Quick does not mean skip testing. Before committing:
 

package/commands/gsd-t-resume.md

@@ -15,8 +15,9 @@ You are resuming work after an interruption. This handles both same-session paus
 
 Read in this exact order:
 1. `CLAUDE.md` — project context and conventions
-2. `.gsd-t/progress.md` — current status, decisions, blockers
-3. `.gsd-t/contracts/` — all contract files
+2. **Check for continue-here files first**: List `.gsd-t/continue-here-*.md` files. If any exist, read the most recent one (highest timestamp). It contains exact position, next action, and open items — use this as the primary resume point.
+3. `.gsd-t/progress.md` — current status, decisions, blockers (always read this too)
+4. `.gsd-t/contracts/` — all contract files
 4. `.gsd-t/domains/*/scope.md` — domain boundaries
 5. `.gsd-t/domains/*/tasks.md` — task lists with completion status
 6. `.gsd-t/domains/*/constraints.md` — domain rules
@@ -25,13 +26,15 @@ Read in this exact order:
 
 ## Step 2: Determine Current Position
 
-From progress.md (or conversation context if same-session), identify:
+From the continue-here file (if present) OR progress.md (or conversation context if same-session), identify:
 - Current milestone and status
 - Which phase we're in
 - Which tasks are done, in progress, or blocked
 - Any pending decisions or user-input-needed items
 - Last entry in the Decision Log
 
+**If a continue-here file was found**: Use its "Next Action" field as the primary resume point. The continue-here file is more precise than progress.md alone. After resuming, delete the continue-here file (it has been consumed).
+
 ## Step 3: Report and Continue
 
 **Level 3 (Full Auto)**: Log a brief status line and auto-resume from the current task/phase. Do NOT wait for user input.

package/commands/gsd-t-scan.md

@@ -2,6 +2,24 @@
 
 You are the lead agent performing a comprehensive analysis of an existing codebase. Your job is to understand the architecture, identify business rules, surface vulnerabilities, find inefficiencies, and produce an actionable tech debt register.
 
+## Step 0: Launch via Subagent
+
+Scans are long-running and context-heavy. Always execute via a Task subagent for a fresh context window.
+
+**If you are the orchestrating agent** (you received the slash command directly):
+Spawn a fresh subagent using the Task tool:
+```
+subagent_type: general-purpose
+prompt: "You are running gsd-t-scan. Working directory: {current project root}
+Read CLAUDE.md and .gsd-t/progress.md for project context, then execute gsd-t-scan starting at Step 1.
+IMPORTANT: Step 2 requires team mode — spawn 5 teammates (architecture, business-rules, security, quality, contracts)
+running in parallel. Do not skip team mode or run dimensions sequentially."
+```
+Wait for the subagent to complete. Relay its summary to the user. **Do not execute Steps 1+ yourself.**
+
+**If you are the spawned subagent** (your prompt says "starting at Step 1"):
+Continue to Step 1 below. At Step 2, use team mode — spawn the 5 teammates in parallel.
+
 ## Step 1: Load Existing Context
 
 Read:
@@ -22,15 +40,15 @@ ALL TEAMMATES read first:
 - CLAUDE.md (if exists)
 - .gsd-t/contracts/ (if exists)
 
-- Teammate "architecture": Analyze project structure, tech stack,
+- Teammate "architecture" (model: haiku): Analyze project structure, tech stack,
   data flow, patterns. Write findings to .gsd-t/scan/architecture.md
-- Teammate "business-rules": Extract all embedded business logic,
+- Teammate "business-rules" (model: haiku): Extract all embedded business logic,
   validation, auth rules, workflows. Write to .gsd-t/scan/business-rules.md
-- Teammate "security": Full security audit — auth, injection, exposure,
+- Teammate "security" (model: sonnet): Full security audit — auth, injection, exposure,
   dependencies. Write to .gsd-t/scan/security.md
-- Teammate "quality": Dead code, duplication, complexity, test gaps,
+- Teammate "quality" (model: sonnet): Dead code, duplication, complexity, test gaps,
   performance, stale deps. Write to .gsd-t/scan/quality.md
-- Teammate "contracts": Compare .gsd-t/contracts/ to actual implementation,
+- Teammate "contracts" (model: haiku): Compare .gsd-t/contracts/ to actual implementation,
   find drift and undocumented interfaces. Write to .gsd-t/scan/contract-drift.md
   (skip if no contracts exist)