@esoteric-logic/praxis-harness 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeffrey Attoh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,192 @@
+# Praxis
+
+> *"Philosophy must be practiced, not just studied."* — Musonius Rufus
+
+A layered harness for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Universal workflow discipline + domain-specific AI-Kits + persistent vault integration.
+
+## What it does
+
+Praxis gives Claude Code a three-layer operating system:
+
+**Universal base** — always loaded. [GSD](https://github.com/gsd-build/get-shit-done) structures work (spec → plan → execute → verify). [Superpowers](https://github.com/obra/superpowers) enforces quality (TDD, debugging, code review). [Ralph](https://github.com/snarktank/ralph) runs autonomous execution loops.
+
+**AI-Kits** — activated on demand via `/kit:<name>`. Each kit bundles domain-specific rules, skills, MCP servers, and slash commands. Activate the web-designer kit and your components get design system enforcement, accessibility auditing, and production lint. Deactivate with `/kit:off`.
+
+**Project config** — per-repo rules that fire automatically based on file paths. Terraform rules load when you touch `.tf` files. GitHub Actions rules load when you touch workflow YAML. No manual switching.
+
+## Quick start
+
+```bash
+npx praxis-harness
+```
+
+One command. Copies rules, commands, skills, and kits directly into `~/.claude/`. Node.js 18+ must be installed first.
+
+**Subsequent commands:**
+```bash
+npx praxis-harness update      # re-copy from latest npm version
+npx praxis-harness health      # verify install integrity
+npx praxis-harness uninstall   # remove Praxis-owned files from ~/.claude/
+```
+
+## After install
+
+Open Claude Code and run:
+
+```
+/plugin marketplace add obra/superpowers-marketplace
+/plugin install superpowers@superpowers-marketplace
+/plugin marketplace add snarktank/ralph
+/plugin install ralph-skills@ralph-marketplace
+```
+
+Verify with `/help` — you should see GSD, Superpowers, and Praxis commands.
+
+## Workflow
+
+The standard GSD workflow for feature development:
+
+```
+/standup           → orient (reads status.md, surfaces stale state)
+/gsd:discuss       → frame the problem (SPEC questions, scope guard)
+/discover          → research options with confidence levels (before /spec)
+/gsd:plan-phase    → plan milestones (with dependency ordering + boundaries)
+/gsd:execute       → implement one milestone at a time (file-group isolation)
+/gsd:verify        → validate (test/lint/typecheck/build, self-review, UNIFY)
+/session-retro     → capture learnings, update vault
+```
+
+For pure bugfixes: `/debug` (test-first debugging, skips GSD).
+For code review: `/review` (launches subagent review at any time).
+For technical research: `/discover` (structured options evaluation before decisions).
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `gsd-discuss` | Frame the problem, SPEC questions, scope guard |
+| `gsd-execute` | Implement one milestone with file-group isolation + boundary enforcement |
+| `gsd-verify` | Validate milestone (test/lint/build), self-review, UNIFY phase summary |
+| `ralph` | Autonomous multi-story execution from a PRD |
+| `plan` | Create a dated work plan with milestone dependencies + checkpoints |
+| `spec` | Create a structured spec or ADR with conflict detection |
+| `discover` | Structured technical discovery with confidence-rated options |
+| `standup` | Session-start orientation from vault state |
+| `risk` | Add a risk register entry to the vault |
+| `kit` | Activate/deactivate an AI-Kit |
+| `review` | Manual code review via subagent |
+| `debug` | Structured test-first debugging |
+| `context-reset` | Reload context from vault without clearing session |
+
+## Rules
+
+15 rules across universal and scoped categories. Universal rules load every session. Scoped rules load only when matching file patterns are detected.
+
+Key additions in this version:
+- **context-management** — context brackets (FRESH/MODERATE/DEPLETED/CRITICAL) adapt behavior to session stage
+- **vault** — multi-backend vault integration (obsidian, logseq, plain, custom)
+
+## Ralph
+
+Ralph is the autonomous execution mode for multi-story work. Use it when you have >5 independent stories that don't require human checkpoints.
+
+1. Write a PRD using `/prd-writer` (structured story format with file groups and estimates)
+2. Run `/ralph` to begin autonomous execution
+3. Each story runs in a fresh context with its own verify cycle
+4. Blocked stories are recorded and skipped — reported at run end
+
+Ralph is not a replacement for GSD — it runs GSD internally per story. Use GSD for work that needs cross-story reasoning or architectural decisions.
+
+## Architecture
+
+```
+┌────────────────────────────────────────┐
+│  Project config                        │
+│  .claude/rules/*.md (path-scoped)      │
+├────────────────────────────────────────┤
+│  AI-Kit (/kit:web-designer)            │
+│  Skills chain + domain rules + MCPs    │
+├────────────────────────────────────────┤
+│  Universal base (always loaded)        │
+│  GSD → Superpowers → Ralph             │
+├────────────────────────────────────────┤
+│  Vault layer                           │
+│  obsidian | logseq | plain | custom    │
+├────────────────────────────────────────┤
+│  Claude Code                           │
+│  ~/.claude/ + plugins + subagents      │
+└────────────────────────────────────────┘
+```
+
+**Workflow hierarchy:** GSD owns the outer loop (discuss → plan → execute → verify). Superpowers enforces quality inside execution (TDD, review, debug). Ralph runs autonomous multi-story iterations. Kits inject domain context into this workflow — they don't replace it.
+
+## Available kits
+
+| Kit | Activate | What it does |
+|-----|----------|-------------|
+| web-designer | `/kit:web-designer` | Design system init → component build → accessibility audit → production lint |
+| infrastructure | `/kit:infrastructure` | Terraform plan → apply → drift detection → compliance check |
+
+More kits coming. See `docs/creating-a-kit.md` to build your own.
+
+## Vault integration
+
+Praxis integrates with a persistent vault for project state, session learnings, and architecture decisions. Four backends are supported:
+
+| Backend | Description | Search tool |
+|---------|-------------|-------------|
+| `obsidian` | Obsidian vault (default) | [Obsidian CLI](https://obsidian.md) |
+| `logseq` | Logseq graph | ripgrep |
+| `plain` | Plain markdown directory (`~/.praxis-vault`) | ripgrep |
+| `custom` | Any directory you choose | ripgrep |
+
+The backend and vault path are configured per machine during install:
+
+```json
+{
+  "vault_path": "/Users/you/Documents/Obsidian",
+  "vault_backend": "obsidian",
+  "vault_name": "My Vault",
+  "repo_path": "/Users/you/repos/praxis"
+}
+```
+
+- **obsidian**: requires [Obsidian CLI](https://obsidian.md) (enable in Obsidian Settings > General > Command line interface). Obsidian must be running for vault search.
+- **logseq/plain/custom**: uses ripgrep for vault search — no extra dependencies
+
+## Updating
+
+```bash
+npx praxis-harness update
+```
+
+Re-copies all files from the latest npm package version. Config file is preserved.
+
+## Uninstalling
+
+```bash
+npx praxis-harness uninstall
+```
+
+Removes all Praxis-owned files from `~/.claude/`. Does not delete config, vault templates, or installed plugins.
+
+## Development
+
+```bash
+git clone https://github.com/arcanesme/praxis.git
+cd praxis
+bash install.sh
+```
+
+The git-clone + `install.sh` path uses symlinks instead of copies, so edits in the repo are immediately reflected.
+
+## Requirements
+
+- macOS or Linux
+- Claude Code CLI
+- Node.js 18+
+- Obsidian, Logseq, or a plain markdown directory (optional, for vault integration)
+
+## License
+
+MIT

package/base/CLAUDE.md

@@ -0,0 +1,148 @@
+# ═══════════════════════════════════════════════════════════════
+# GLOBAL CLAUDE.MD — Praxis Execution Engine
+# Location: ~/.claude/CLAUDE.md | Applies to ALL projects, ALL sessions
+# MAP: This file is ~100 lines. Detail lives in ~/.claude/rules/
+# ═══════════════════════════════════════════════════════════════
+
+## Identity
+You are a senior engineering partner. Think before you build. Verify before you report. Repair before you proceed.
+- No flattery. No filler. Be skeptical. Be concise.
+- If intent is unclear, ask. Do not guess.
+- Tell me when I am wrong. If a better approach exists, say so.
+- Never say "looks good" about your own output.
+- Every option presented MUST include a recommendation and why.
+
+## Workflow Hierarchy
+- **GSD** owns the outer loop: discuss → plan → execute → verify → simplify → ship.
+  Always start feature work with GSD.
+- **Superpowers** enforces quality inside execution (TDD, review, debug).
+  Its skills auto-activate — never invoke them alongside GSD phases.
+- **Ralph** runs autonomous multi-story iterations from the terminal.
+- **Kits** inject domain context into this workflow — they don't replace it.
+- Never invoke `/superpowers:write-plan` alongside `/gsd:plan-phase`.
+- Pure bugfixes: skip GSD, use Superpowers debugging directly.
+- After every implementation: run `/simplify` to clean up code before verify.
+- Use `/verify-app` for end-to-end checks, `/ship` when ready to commit+push+PR.
+
+## Plan Mode Protocol
+For non-trivial tasks (3+ steps):
+1. Start in Plan Mode — iterate on the plan until it's solid
+2. Switch to auto-accept edits and let Claude one-shot the implementation
+3. Run `/simplify` after implementation
+4. Run `/verify-app` to confirm everything works
+5. Run `/ship` to commit, push, and PR
+
+## Error Learning
+When a mistake is corrected: update project CLAUDE.md `## Error Learning` section
+with a specific, actionable rule to prevent recurrence. Each correction becomes
+permanent institutional memory. Don't wait for session-retro — fix the rule immediately.
+
+## Non-Negotiables (fire every session)
+
+**Before any non-trivial task:**
+- WHAT / DONE-WHEN / CONSTRAINTS / NON-GOALS — answer all four before starting.
+
+**Stop-and-Fix Rule:** Validation fails → fix now → re-validate → proceed.
+If cannot fix in 3 attempts: STOP. Report What / So What / Now What.
+
+**Before every commit:**
+1. Secret scan: `rg "(sk-|ghp_|pplx-|AKIA|Bearer [A-Za-z0-9+/]{20,})" $(git diff --staged --name-only)`
+2. Lint + typecheck — no commits with warnings or errors.
+3. `git --no-pager config user.email` → must match expected identity. If mismatch: STOP.
+
+**Before writing any templated file:** Scan for unreplaced `{placeholder}` patterns. Zero must remain.
+
+## Vault Configuration
+Vault path and backend are machine-specific. Read from `~/.claude/praxis.config.json`:
+```json
+{ "vault_path": "/path/to/vault", "vault_backend": "obsidian" }
+```
+Supported backends: `obsidian` (default), `logseq`, `plain`, `custom`.
+If config file is missing: tell the user to run `praxis/install.sh`.
+All `{vault_path}` references in rules and skills resolve from this config.
+
+## Durable Memory
+Context is volatile. Files are permanent. Act accordingly.
+
+| Purpose | Location |
+|---------|----------|
+| Execution plans | `{vault_path}/plans/YYYY-MM-DD_[task-slug].md` |
+| Project state (human) | `{vault_path}/status.md` |
+| Project state (machine) | `{vault_path}/claude-progress.json` |
+| Project metadata | `{vault_path}/_index.md` |
+| Learnings | `{vault_path}/notes/learnings.md` |
+
+## Vault Protocol
+- ALWAYS run a vault search before reading vault files (see vault.md backend table).
+- Obsidian indexes in real-time — no manual update command needed.
+- Link format: obsidian → `[[wikilinks]]`; logseq/plain/custom → standard markdown links.
+- Detect project from CWD matching `local_path` in `_index.md`.
+
+## MCP Servers
+Registered via `claude mcp add`. Persist globally across sessions.
+
+| Server | Purpose | API Key |
+|--------|---------|---------|
+| context7 | Live library/API docs | None |
+| perplexity | AI web search | `PERPLEXITY_API_KEY` |
+| github | Repo operations, PRs, issues | `GITHUB_PERSONAL_ACCESS_TOKEN` |
+
+Check: `claude mcp list` | Manage: `bash scripts/onboard-mcp.sh [server|all]`
+Missing servers are non-blocking — features degrade gracefully.
+
+## After Compaction — Bootstrap
+1. Read project CLAUDE.md (always first)
+2. Check `claude-progress.json` — if `.ralph_state.current_story` is set: read it NOW, it is authoritative
+3. Active task? → read active plan current milestone only
+   No active task? → read `status.md`
+4. Load rules only for what the current task touches:
+   - Terraform/Azure → `~/.claude/rules/terraform.md`
+   - GitHub Actions → `~/.claude/rules/github-actions.md`
+   - PowerShell scripts → `~/.claude/rules/powershell.md`
+   - Git operation → `~/.claude/rules/git-workflow.md`
+   - Security concern → `~/.claude/rules/security.md`
+
+## Core Anti-Patterns (NEVER)
+- Silently swallow errors or use empty catch blocks
+- Claim "tests pass" without running them and showing output
+- Keep plans, specs, or decisions only in conversation memory
+- Proceed past a failed milestone
+- Expand scope without asking
+- Hardcode secrets or credentials
+- Commit with wrong git identity
+- Write a file with unreplaced {placeholders}
+- Use vault search when Obsidian is not running (obsidian backend requires Obsidian open)
+
+## AI-Kit Registry
+Kits activate via `/kit:<n>` slash command. Kits are idempotent — double-activate is a no-op.
+
+| Kit | Activate | Domain |
+|-----|----------|--------|
+| web-designer | `/kit:web-designer` | Design system → components → accessibility → production lint |
+| infrastructure | `/kit:infrastructure` | Terraform → Azure → GitHub Actions → compliance |
+
+Kit manifests live in `~/.claude/kits/<name>/KIT.md`.
+
+## Rules Registry — Load on Demand Only
+
+### Universal — always active
+| File | Purpose |
+|------|---------|
+| `~/.claude/rules/profile.md` | Who the user is, active projects, identities |
+| `~/.claude/rules/execution-loop.md` | SPEC/PLAN/VALIDATE loop enforcement |
+| `~/.claude/rules/coding.md` | Context7 mandate, error handling, no hardcodes |
+| `~/.claude/rules/code-quality.md` | Language-agnostic quality standards |
+| `~/.claude/rules/git-workflow.md` | Commits, branches, identity verification |
+| `~/.claude/rules/security.md` | Secrets, credentials, auth patterns |
+| `~/.claude/rules/communication.md` | Client writing, no AI attribution |
+| `~/.claude/rules/vault.md` | Second brain integration — obsidian, logseq, or plain markdown |
+| `~/.claude/rules/architecture.md` | ADR format, What/So What/Now What, risk docs |
+| `~/.claude/rules/context-management.md` | GSD/Ralph anti-rot, context reset protocol |
+
+### Scoped — load only when paths match
+| File | Loads when |
+|------|------------|
+| `~/.claude/rules/azure.md` | `**/*.tf`, `**/*.bicep`, `**/*.azcli` |
+| `~/.claude/rules/terraform.md` | `**/*.tf`, `**/*.tfvars` |
+| `~/.claude/rules/github-actions.md` | `.github/workflows/**` |
+| `~/.claude/rules/powershell.md` | `**/*.ps1`, `**/*.psm1` |

package/base/commands/context-reset.md

@@ -0,0 +1,72 @@
+---
+description: Checkpoint current session state to vault files before a context reset. Use when context degradation is detected (repeated corrections, loop behavior, instruction drift).
+---
+
+You are preparing a clean context reset for the current session.
+
+**Step 1 — Identify project context**
+- Read vault_path from `~/.claude/praxis.config.json`
+- Detect project from CWD matching `local_path` in vault `_index.md`
+- If no project detected: ask which project before continuing
+
+**Step 2 — Read current state**
+- Read the active plan file (from `status.md` → `current_plan:` field)
+- Read `claude-progress.json` for machine state
+- Identify: current milestone, last 3 decisions, any STOP conditions or blockers
+
+**Step 3 — Write context checkpoint**
+Write a standalone checkpoint file at `{vault_path}/plans/current-phase-summary.md`:
+
+```markdown
+---
+tags: [checkpoint, {project-slug}]
+date: {YYYY-MM-DD}
+source: agent
+---
+# Context Checkpoint — {YYYY-MM-DD HH:MM}
+
+## Active Plan
+{plan filename}
+
+## Last Milestone Completed
+{milestone name and status}
+
+## Decisions (last 3)
+1. {decision} — {rationale}
+2. {decision} — {rationale}
+3. {decision} — {rationale}
+
+## Active STOP Conditions
+{any blockers or stop conditions, or "None"}
+
+## Next Step
+{what should happen when the session resumes}
+```
+
+**Step 4 — Update status.md**
+Update `status.md` with current What / So What / Now What:
+- **What**: what was accomplished before the reset
+- **So What**: why the reset is happening (context degradation symptoms)
+- **Now What**: resume from the checkpoint in the active plan
+
+**Step 5 — Update claude-progress.json**
+Write a session snapshot to `claude-progress.json`:
+- Update `last_session` with current date and a note about the context reset
+- If Ralph is active: preserve `ralph_state` exactly as-is
+
+**Step 6 — Instruct the user**
+Print:
+```
+Context checkpoint saved to:
+  Checkpoint: {vault_path}/plans/current-phase-summary.md
+  Status:     {vault_path}/status.md
+  Progress:   {vault_path}/claude-progress.json
+
+Run /clear to reset context, then paste this bootstrap prompt:
+
+  Context reset. Bootstrap:
+  1. Read project CLAUDE.md
+  2. Read {vault_path}/plans/{current-plan}
+  3. Read {vault_path}/plans/current-phase-summary.md
+  4. Resume from milestone: {milestone-name}
+```

package/base/commands/debug.md

@@ -0,0 +1,63 @@
+---
+description: Structured test-first debugging. Reproduce the bug, write a failing test, isolate root cause, fix, verify. Use for pure bugfixes — skips GSD phases.
+---
+
+You are running structured debugging.
+
+**Step 1 — Gather bug report**
+Ask for all of these (accept partial, fill gaps from code):
+- **Observed behavior**: What actually happens?
+- **Expected behavior**: What should happen instead?
+- **Reproduction steps**: Exact sequence to trigger the bug.
+- **Suspect files**: Where in the code does the user think the bug is?
+- **When it last worked**: What changed since then? (check `git log` if unknown)
+
+If the user provides an error message or stack trace: use that as the starting point.
+
+**Step 2 — Write a failing test**
+Before touching any implementation code:
+1. Write a test that demonstrates the bug — it MUST fail.
+2. Run the test. Confirm it fails with the expected error.
+3. If the test passes: re-examine the bug report. The reproduction may be wrong,
+   or the bug may not be where the user thinks.
+4. Show the failing test output.
+
+**Step 3 — Isolate root cause**
+- Read suspect files. Trace the code path from input to failure.
+- Use `rg` to find related call sites, error handlers, recent changes.
+- State the root cause in one sentence:
+  `Root cause: {what is wrong} in {file}:{line} because {why}.`
+- If root cause is unclear after tracing: add diagnostic logging or breakpoints,
+  reproduce again, and narrow down.
+
+**Step 4 — Fix the root cause**
+- Fix the root cause, not the symptom. Keep the fix minimal.
+- Do not refactor surrounding code as part of the fix.
+- Do not add unrelated improvements.
+- If the fix requires changing the test: explain why the original test was wrong.
+
+**Step 5 — Verify**
+1. Run the failing test from Step 2 — it MUST now pass.
+2. Run the full test suite — no regressions.
+3. Run the linter — clean.
+4. Show all output.
+
+**Step 6 — Write learnings**
+- Read vault_path from `~/.claude/praxis.config.json`
+- If this bug represents a pattern (not a one-off typo):
+  write a `[LEARN:bugfix]` entry to `{vault_path}/notes/learnings.md`:
+  ```markdown
+  ## [LEARN:bugfix] {Short title}
+  - **What**: {what went wrong}
+  - **So What**: {why it matters, how it could recur}
+  - **Now What**: {what to do to prevent recurrence}
+  - **Date**: {YYYY-MM-DD}
+  ```
+- Vault indexing is automatic.
+
+**Rules:**
+- Never fix without first reproducing.
+- Never say "fixed" without showing the test passing.
+- Skips GSD phases — for pure bugfixes only.
+- If the "bug" is actually a feature gap: redirect to `/gsd:discuss`.
+- If the fix touches >5 files: it is not a bugfix. Use GSD.

package/base/commands/discover.md

@@ -0,0 +1,49 @@
+---
+description: Structured technical discovery — evaluate options, make recommendations with confidence levels. Use before /spec when you need to research before deciding.
+---
+
+You are running a structured technical discovery.
+
+**Step 1 — Frame the question**
+- Read vault_path from `~/.claude/praxis.config.json`
+- What decision needs to be made? (one sentence)
+- What are the constraints? (compliance, performance, compatibility, cost)
+- What is already known? (run `obsidian search query="{topic}" limit=5`)
+
+**Step 2 — Research options**
+- Identify 2-4 viable options. For each:
+  - Name and one-sentence description
+  - Pros (concrete, measurable)
+  - Cons (concrete, measurable)
+  - Confidence: HIGH / MEDIUM / LOW (how certain are you this works?)
+- Use Context7 for library/API evaluation. Use subagents for codebase exploration.
+- Never recommend an option you haven't verified against constraints.
+
+**Step 3 — Recommend**
+- State the recommended option with rationale
+- If confidence is LOW on all options: say so. Recommend a spike or prototype.
+- Format:
+  ```
+  Recommendation: {option}
+  Confidence: {HIGH/MEDIUM/LOW}
+  Rationale: {why this over alternatives}
+  Risk: {what could go wrong}
+  ```
+
+**Step 4 — Write to vault**
+- Write `{vault_path}/research/{YYYY-MM-DD}_{kebab-topic}.md` with frontmatter:
+  ```yaml
+  ---
+  tags: [research, {project-slug}]
+  date: {YYYY-MM-DD}
+  status: complete
+  source: agent
+  ---
+  ```
+- Include all options evaluated, recommendation, and confidence
+- Report: "Discovery written. Run `/spec` to formalize as ADR, or `/gsd:discuss` to proceed."
+
+**Rules:**
+- Discovery is research, not implementation. Zero code output.
+- If the question is already answered by an existing spec: point to it instead.
+- Fills the gap between `/gsd:discuss` (problem framing) and `/spec` (formal decision).

package/base/commands/gsd-discuss.md

@@ -0,0 +1,53 @@
+---
+description: Entry point for all feature work. Frames the problem, gathers SPEC questions, and recommends next phase. Use before /gsd:plan-phase.
+---
+
+You are starting the GSD discuss phase — framing the problem before planning.
+
+**Step 1 — Load minimal context**
+- Read vault_path from `~/.claude/praxis.config.json`
+- Detect project from CWD matching `local_path` in vault `_index.md`
+- If no project detected: ask which project before continuing
+
+**Step 2 — Read ONLY these files (nothing else)**
+1. `{vault_path}/status.md` — current state and blockers
+2. Active plan (if `current_plan:` is set in status.md) — skim objectives only
+3. `~/.claude/rules/profile.md` — user context
+
+Do NOT load rules, kit context, or session history at this phase.
+
+**Step 3 — Search for related work**
+Run: `obsidian search query="{topic}" limit=5`
+Check if specs, prior plans, or research already exist for this topic.
+
+**Step 4 — SPEC questions**
+Ask the user to answer all four:
+- **WHAT**: Concrete deliverable (not vague goals)
+- **DONE-WHEN**: Specific checks that prove completion
+- **CONSTRAINTS**: Performance, compatibility, style requirements
+- **NON-GOALS**: What this task explicitly does NOT include
+
+If answers are ambiguous: ask 2–3 follow-up questions. Do not proceed with vague scope.
+
+**Step 5 — Problem framing**
+Output a 1-paragraph problem framing that includes:
+- What exists today (from status.md / vault search)
+- What gap or need the user described
+- Recommendation: proceed to `/gsd:plan-phase` or write a `/spec` first
+
+**Step 5b — Scope guard**
+- Problem framing (Step 5 output) must not exceed 200 words. If the problem
+  requires more to frame: it is too large. Split into sub-problems and run
+  `/gsd:discuss` on each separately.
+- After framing: explicitly list what is NOT being decided in this discuss phase.
+- Never output implementation code, pseudocode, or file-level changes during discuss.
+  This phase produces a problem statement, not a solution.
+- If the framing implies >5 milestones or >3 file groups: flag as scope explosion
+  risk and recommend splitting before `/gsd:plan-phase`.
+
+**Step 6 — Handoff**
+End with: "Run `/gsd:plan-phase` to continue, or `/spec` if this needs a design spec first."
+
+**Rules:**
+- Problem framing is a paragraph, not a design doc.
+- If scope exceeds 5 milestones: recommend splitting into multiple GSD passes.

package/base/commands/gsd-execute.md

@@ -0,0 +1,60 @@
+---
+description: Implementation phase — loads scoped context and works one milestone at a time. Use after plan is approved.
+---
+
+You are executing the GSD implementation phase.
+
+**Step 1 — Load implementation context**
+- Read vault_path from `~/.claude/praxis.config.json`
+- Read `{vault_path}/status.md` → get `current_plan:`
+- Read the active plan file — focus on the CURRENT milestone only (not full plan)
+- If no active plan: STOP. Tell user to run `/gsd:discuss` first.
+
+**Step 2 — Load scoped rules**
+Load ONLY rules relevant to files being touched in this milestone:
+- Terraform/Azure files → `~/.claude/rules/terraform.md`, `~/.claude/rules/azure.md`
+- GitHub Actions → `~/.claude/rules/github-actions.md`
+- PowerShell → `~/.claude/rules/powershell.md`
+- Git operations → `~/.claude/rules/git-workflow.md`
+- Security-sensitive changes → `~/.claude/rules/security.md`
+
+Do NOT load all rules. Context is scarce — spend it on implementation, not instructions.
+
+**Step 2b — Declare file group and load boundaries**
+Before implementing the current milestone, declare the file group:
+- Format: `Milestone: {name} | Files: {list, max 5} | Off-limits: everything else`
+- Write the file-group declaration to the plan file under the milestone entry.
+- File groups can include globs (e.g., `src/components/*.tsx`).
+- Read `## Boundaries` from the active plan. Boundary items are absolute off-limits —
+  they override file-group declarations. If a milestone file group includes a
+  boundary-protected file: STOP. Surface the conflict before proceeding.
+- If current milestone has `checkpoint: decision` or `checkpoint: human-verify`:
+  present the decision/output to user before proceeding. Do not auto-advance.
+
+**Step 3 — Implement current milestone**
+- One milestone at a time. Keep diffs scoped.
+- Do not expand scope without explicit user approval.
+- Use extended thinking for tasks touching >3 files or requiring architectural decisions.
+- Before writing to or editing any file: check if it is in the declared file group.
+- If a required change is discovered in an off-limits file: STOP.
+  Surface as a new milestone candidate. Do not expand current milestone.
+- Milestone diff must touch ONLY declared files. Undeclared file change = scope violation.
+
+**Step 4 — Milestone completion**
+When the milestone is complete:
+1. Write a brief summary to the active plan file under the milestone entry
+2. Confirm actual diff matches declared file group
+3. Output ONE recommendation — no menu, no alternatives:
+   `Next: /gsd:verify` followed by one sentence explaining why
+   Example: "Next: /gsd:verify — 3 files changed in declared group, tests and lint needed"
+
+**Step 5 — Ralph handoff trigger**
+If remaining milestones >5 and all are independent (no cross-milestone reasoning):
+- After `/gsd:verify` passes (not during Step 4), append:
+  "Also consider: /ralph — {n} independent milestones remaining"
+- Never surface Ralph before verify completes.
+
+**Rules:**
+- Never skip a milestone or reorder without approval.
+- If blocked: document the blocker in the plan file, suggest alternatives or escalate.
+- One feature per session. Do not mix unrelated tasks.