@esoteric-logic/praxis-harness 1.1.0

package/base/skills/scaffold-new/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: scaffold-new
+disable-model-invocation: true
+description: Scaffold a brand new project into the full harness. Invoke with /scaffold-new only.
+  Creates repo CLAUDE.md, vault subtree, git identity verification, gitignore,
+  pre-commit hook, and Project Registry entry. Side-effect skill — never auto-triggers.
+---
+
+# scaffold-new Skill
+
+## Vault Path Resolution
+Read vault_path from `~/.claude/praxis.config.json` at the start of every invocation.
+If config is missing: STOP. Tell user to run `praxis/install.sh`.
+
+## NON-GOALS — Rules Loading
+- Do NOT load `git-workflow.md` — identity and init handled inline
+- Do NOT load `security.md` — not relevant during scaffolding
+- Do NOT load `terraform.md` or `github-actions.md` — no infra files touched
+
+## Overview
+Scaffolds a new project in phases:
+1. **Phase 0**: Validate git identity before anything touches disk
+2. **Phase 1**: Gather project metadata
+3. **Phase 2**: Scaffold repo `CLAUDE.md`
+4. **Phase 3**: Scaffold vault subtree
+5. **Phase 3.5**: Scaffold `claude-progress.json`
+6. **Phase 4**: Vault search check
+7. **Phase 5**: Git init (if new repo)
+8. **Phase 5.5**: Install git hooks (optional)
+9. **Phase 6**: Update Project Registry + agenda.md
+10. **Phase 7**: Confirm and open Obsidian
+
+---
+
+## Phase 0 — Identity Guard
+
+From the user's stated project type, resolve the expected identity.
+<!-- CUSTOMIZE: Replace with your git identities in profile.md -->
+Read identity table from `~/.claude/rules/git-workflow.md`.
+
+**Validation steps:**
+1. Confirm `{repo_root}` falls under the correct `includeIf` directory.
+   If not: **STOP**. Report the mismatch.
+2. If repo exists: run `git --no-pager config user.email` and confirm match.
+   If mismatch: **STOP**. Report `expected: X, got: Y`.
+3. Store resolved values: `{identity_profile}`, `{ssh_key}`, `{identity_email}`
+
+---
+
+## Phase 1 — Gather Info
+
+Before asking, run vault duplicate check:
+```bash
+obsidian search query="{slug}" path="01_Projects" limit=3
+```
+
+Ask in one message:
+- **Project name** — display name
+- **Project slug** — kebab-case (confirm derivation from name)
+- **One-line description**
+- **Type** — Work / Personal
+- **Tech stack** — 1–5 items, comma-separated
+- **Repo root path**
+- **Repo URL** — (use `TBD` if not yet created)
+- **New or existing repo?**
+
+**Computed values:**
+```
+vault_path   = {config.vault_path}/01_Projects/{type}/_active/{slug}
+today_date   = current date YYYY-MM-DD
+```
+
+---
+
+## Phase 2 — Scaffold repo CLAUDE.md
+
+1. Read `references/repo-CLAUDE-md-template.md`
+2. Apply full substitution map. All placeholders must resolve.
+3. Scan output for remaining `{placeholder}` patterns. Resolve before writing.
+4. Write to `{repo_root}/CLAUDE.md`
+
+---
+
+## Phase 3 — Scaffold Vault
+
+Create directories:
+```bash
+mkdir -p {vault_path}/plans {vault_path}/notes {vault_path}/specs {vault_path}/research
+```
+
+Create files from templates in `references/`:
+- `_index.md` from `vault-index-template.md`
+- `status.md` from `vault-status-template.md` (`current_plan:` empty)
+- `tasks.md` from `vault-tasks-template.md`
+- `notes/learnings.md` from `vault-learnings-template.md`
+- `.gitignore` from `gitignore-template.txt` (new repos only)
+
+---
+
+## Phase 3.5 — Scaffold claude-progress.json
+
+From `references/claude-progress-template.json`. Apply substitution map.
+Write to `{vault_path}/claude-progress.json`.
+
+---
+
+## Phase 4 — Vault Search Check
+
+Vault indexing is automatic for `obsidian` backend. No manual re-index needed.
+Verify the new project is searchable: `obsidian search query="{slug}" limit=1`
+On failure: warn, do not block.
+
+---
+
+## Phase 5 — Git Init (if new repo)
+
+```bash
+git init {repo_root}
+git -C {repo_root} add CLAUDE.md
+git -C {repo_root} commit -m "chore: initialize project scaffold"
+```
+After commit: verify `git config user.email` matches. If mismatch: **STOP**.
+
+---
+
+## Phase 5.5 — Git Hooks (ask first)
+
+Ask: "Generate and install a pre-commit lint hook?"
+If yes: invoke the `pre-commit-lint` skill.
+If no: skip silently.
+
+---
+
+## Phase 6 — Update Project Registry
+
+Append to vault CLAUDE.md Project Registry table and agenda.md.
+Vault indexing is automatic.
+
+---
+
+## Phase 7 — Confirm & Open Vault
+
+Open the vault in the user's app (backend-conditional):
+- `obsidian` → `open "obsidian://open?vault=Obsidian"`
+- `logseq` → `open "logseq://graph/{vault_name}"`
+- `plain` / `custom` → print vault path for user to open manually
+
+Print summary table with all created files and bootstrap sequence.
+
+---
+
+## Execution Checklist
+
+- [ ] Phase 0: Identity resolved and validated
+- [ ] Phase 1: All metadata collected
+- [ ] Phase 2: `{repo_root}/CLAUDE.md` — zero unreplaced placeholders
+- [ ] Phase 3: Vault subtree created
+- [ ] Phase 3.5: `claude-progress.json` created
+- [ ] Phase 4: Vault search check (automatic indexing)
+- [ ] Phase 5: Git identity verified
+- [ ] Phase 5.5: Hook decision made
+- [ ] Phase 6: Registry and agenda updated
+- [ ] Phase 7: Summary printed
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| Identity mismatch | STOP. Report. Do not commit. |
+| Files already exist | Ask before overwriting |
+| Unreplaced placeholder | Resolve before writing |
+| Vault search fails | Warn only |
+
+## Removal Conditions
+- Phase 0: Remove after 20+ consecutive correct identity resolutions over 60 days
+- Phase 3.5: Remove when a dedicated MCP tool handles machine-readable state
+- Phase 5.5: Remove when hooks managed globally via dotfiles bootstrap

package/base/skills/scaffold-new/references/claude-progress-template.json

@@ -0,0 +1,24 @@
+{
+  "project": "{slug}",
+  "display_name": "{Project Name}",
+  "created": "{YYYY-MM-DD}",
+  "type": "{type}",
+  "identity": "{identity_profile}",
+  "repo_root": "{repo_root}",
+  "vault_path": "{vault_path}",
+  "stack": ["{stack_item_1}", "{stack_item_2}", "{stack_item_3}"],
+  "milestones": [],
+  "features": [],
+  "ralph_state": {
+    "mode": "idle",
+    "prd_path": null,
+    "current_story": null,
+    "completed_stories": [],
+    "blocked_stories": [],
+    "learnings": [],
+    "last_iteration": null,
+    "session_count": 0
+  },
+  "last_session": null,
+  "sessions": []
+}

package/base/skills/scaffold-new/references/gitignore-template.txt

@@ -0,0 +1,65 @@
+# .gitignore
+# Generated by praxis scaffold-new — review before committing to shared repos
+
+# ── Claude / AI Harness ───────────────────────────────────────────────────
+CLAUDE.md
+.claude/
+.mcp.json
+*.claude-session
+agent-memory.jsonl
+.context7-cache/
+
+# ── Vault References ──────────────────────────────────────────────────────
+.vault-path
+.obsidian-local/
+.obsidian/workspace
+.obsidian/workspace.json
+.logseq/
+
+# ── OS and Editor Noise ───────────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+.vscode/settings.json
+.vscode/launch.json
+.idea/
+
+# ── Secrets and Credentials ───────────────────────────────────────────────
+.env
+.env.*
+!.env.example
+!.env.template
+*.pem
+*.key
+*.p12
+*.pfx
+local.settings.json
+secrets.json
+
+# ── Terraform ─────────────────────────────────────────────────────────────
+.terraform/
+.terraform.lock.hcl
+terraform.tfstate
+terraform.tfstate.*
+*.tfplan
+*.tfvars
+!*.tfvars.example
+
+# ── Node.js ───────────────────────────────────────────────────────────────
+node_modules/
+dist/
+build/
+
+# ── Python ────────────────────────────────────────────────────────────────
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+*.egg-info/
+.mypy_cache/
+.ruff_cache/
+
+# ── Logs and Temp ─────────────────────────────────────────────────────────
+*.log
+*.tmp
+*.cache
+.cache/

package/base/skills/scaffold-new/references/repo-CLAUDE-md-template.md

@@ -0,0 +1,87 @@
+# {Project Name}
+<!-- MAP: This file is ~60 lines. If you're adding explanation, it belongs in ~/.claude/rules/ -->
+
+## Overview
+{one-line description}
+
+## Global Rules
+Inherits execution engine from `~/.claude/CLAUDE.md`.
+Phases (SPEC → PLAN → IMPLEMENT → VALIDATE → REPAIR → COMMIT → LOG → REPEAT),
+self-review protocol, and code quality standards apply without exception.
+
+## Identity
+- **Type**: {type}
+- **Git profile**: {identity_profile}
+- **SSH key**: {ssh_key}
+- **Email**: {identity_email}
+- **includeIf path**: {repo_root}
+
+If `git config user.email` does not return `{identity_email}`, STOP before any commit.
+
+## Vault Project
+- **Vault path**: {vault_path}
+- **Project index**: `{vault_path}/_index.md`
+
+Code lives here. Knowledge, decisions, and plans live in the vault.
+
+| Purpose | Location |
+|---------|----------|
+| Project metadata | `{vault_path}/_index.md` |
+| Execution plans | `{vault_path}/plans/` |
+| Execution state | `{vault_path}/status.md` |
+| Machine-readable state | `{vault_path}/claude-progress.json` |
+| Agent learnings | `{vault_path}/notes/learnings.md` |
+| Specs & decisions | `{vault_path}/specs/` |
+
+## Tech Stack
+- {stack_item_1}
+- {stack_item_2}
+- {stack_item_3}
+
+## Commands
+```bash
+dev:    # fill in as project develops
+test:   # fill in as project develops
+lint:   # fill in as project develops
+build:  # fill in as project develops
+format: # fill in as project develops
+```
+
+## Code Style
+- Prefer simple, readable code over clever abstractions
+- After finishing implementation, run `/simplify` to clean up
+- If a fix feels hacky, find a cleaner solution before finishing
+- No AI-generated comments or attributions in code or commits
+
+## Verification
+- Before marking any task complete, run the test suite
+- Check logs before claiming a bug is fixed
+- End every task instruction with a verification step
+- Use `/verify-app` for end-to-end checks
+
+## Conventions
+- **Commits**: conventional commits (feat:, fix:, docs:, refactor:, test:, chore:)
+- **Branches**: `{type}/{description}` (e.g., `feat/add-auth`, `fix/nsg-rule`)
+- **Plans**: `{vault_path}/plans/YYYY-MM-DD_[task-slug].md`
+- **Learnings**: `{vault_path}/notes/learnings.md` using [LEARN:tag] schema
+
+## Error Learning
+<!-- When a mistake is corrected, write a new rule here to prevent recurrence -->
+<!-- Each rule should be specific and actionable -->
+
+## Project-Specific Rules
+<!-- Add rules discovered during development -->
+
+## After Compaction — Bootstrap Sequence
+
+**Step 1** — Read this file top to bottom first.
+**Step 2** — Active task? → read active plan. No task? → read status.md.
+**Step 3** — Load stack rules only if the current task touches them.
+
+## Compact Preservation
+When compacting, always preserve:
+- Active plan path
+- Current milestone
+- Last 3 decisions and rationale
+- Any STOP conditions or blockers
+- Ralph state (if active): current story, completed stories

package/base/skills/scaffold-new/references/vault-index-template.md

@@ -0,0 +1,31 @@
+---
+tags: [index, {slug}]
+status: active
+repo: {repo_url}
+local_path: {repo_root}
+vault_path: {vault_path}
+tech_stack: [{stack_item_1}, {stack_item_2}, {stack_item_3}]
+started: {YYYY-MM-DD}
+---
+
+# {Project Name}
+
+## Overview
+{one-line description}
+
+## Links
+- **Repo**: [GitHub]({repo_url})
+- **Local**: {repo_root}
+- **Vault**: {vault_path}
+
+## Active Goals
+- [ ] Define initial milestones
+- [ ] Complete project scaffold
+
+## Key Decisions
+<!-- Link decision records here as they are created -->
+
+## Execution State
+- **Status file**: [[{slug}/status]] (What / So What / Now What)
+- **Machine state**: `{vault_path}/claude-progress.json`
+- **Active plan**: see `current_plan:` in status.md

package/base/skills/scaffold-new/references/vault-learnings-template.md

@@ -0,0 +1,21 @@
+---
+tags: [learnings, {slug}]
+date: {YYYY-MM-DD}
+source: agent
+---
+# {Project Name} — Learnings
+
+Agent corrections and discovered patterns for this project.
+Uses the [LEARN:tag] schema from the execution engine.
+
+Tags: `bugfix`, `convention`, `perf`, `security`, `tooling`, `arch`, `process`
+
+<!-- Example entry:
+
+## [LEARN:tooling] Terraform fmt must run before plan
+- **What**: `terraform plan` succeeded but CI failed on formatting check
+- **So What**: Wasted a full CI cycle on a preventable formatting error
+- **Now What**: Always run `terraform fmt -recursive` before `terraform plan`.
+- **Date**: 2026-03-12
+
+-->

package/base/skills/scaffold-new/references/vault-status-template.md

@@ -0,0 +1,21 @@
+---
+tags: [status, {slug}]
+date: {YYYY-MM-DD}
+source: agent
+---
+# {Project Name} — Status
+
+current_plan:
+last_updated: {YYYY-MM-DD HH:MM}
+
+## What (Current State)
+<!-- What is done. What is in progress. What is blocked. Facts only. -->
+
+## So What (Implications & Decisions)
+<!-- Why the current state matters. Key decisions and their rationale. -->
+
+## Now What (Next Actions)
+<!-- Ordered list of what comes next, informed by the above. -->
+
+## Test Debt
+<!-- Flag any skipped tests from spike/prototype work. -->

package/base/skills/scaffold-new/references/vault-tasks-template.md

@@ -0,0 +1,20 @@
+---
+tags: [tasks, {slug}]
+date: {YYYY-MM-DD}
+source: agent
+---
+# {Project Name} — Tasks
+
+## Active
+<!-- Current work items in flight -->
+
+## Backlog
+<!-- Prioritized list of upcoming work -->
+- [ ] Define initial milestones
+- [ ] Complete project scaffold
+
+## Blocked
+<!-- Items blocked by dependencies or decisions -->
+
+## Completed
+<!-- Done items — move here from Active when complete -->

package/base/skills/session-retro/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: session-retro
+disable-model-invocation: true
+description: End-of-session retrospective. Invoke manually with /session-retro only.
+  Writes [LEARN:tag] entries, proposes rule updates, updates claude-progress.json,
+  triggers vault-gc lightweight check. Side-effect skill — never auto-triggers.
+allowed-tools: Bash, Read, Write, Edit
+---
+
+# session-retro Skill
+
+## Vault Path Resolution
+Read vault_path from `~/.claude/praxis.config.json`. If missing: write to fallback location.
+
+## DONE-WHEN
+- [ ] Session summary written (3–5 bullets)
+- [ ] Violations and corrections extracted
+- [ ] [LEARN:tag] entries written to correct learnings.md
+- [ ] Rule proposals surfaced (user approves before writing)
+- [ ] `claude-progress.json` last_session updated
+- [ ] vault-gc lightweight check triggered
+- [ ] `/clear` suggested if session had >2 corrections or scope drift
+
+## NON-GOALS
+- Does not write rules without user approval
+- Does not auto-close or modify open plan files
+- Does not run full vault-gc audit (lightweight only)
+
+---
+
+## Ralph Integration
+When `claude-progress.json` → `ralph_state.mode == "active"`:
+- Run Phase 1 (summary) — required
+- Skip Phase 2 (violation extraction — no user corrections in Ralph)
+- Run Phase 3 (LEARN entries) — required
+- Skip Phase 4 (rule proposals — no user to approve)
+- Run Phase 5 (update claude-progress.json) — required
+  - Push `current_story` to `completed_stories`
+  - Set `current_story` to null
+  - Increment `session_count`
+  - Write `last_iteration` timestamp
+- Run Phase 6 (vault-gc lightweight) — required
+- Run Phase 7 (health) — write to `ralph_state`, always suggest `/clear`
+- Exit 0 always — never block a Ralph iteration
+
+---
+
+## Phase 1 — Summarize Session
+
+Review conversation. Produce 3–5 bullet summary:
+- What was accomplished (concrete deliverables, decisions)
+- What was attempted but not completed (and why)
+- Any scope drift from original intent
+
+## Phase 2 — Extract Violations and Corrections
+
+Scan session for:
+1. **Corrections**: times user corrected Claude's output
+2. **Rule violations**: things a rules file should have blocked
+3. **Missing rules**: patterns that recurred with no rule
+4. **Process violations**: SPEC/PLAN/VALIDATE loop skipped
+
+Classify each: type, tag (`bugfix|convention|perf|security|tooling|arch|process`), impact.
+
+## Phase 3 — Write [LEARN:tag] Entries
+
+For each finding with clear root cause:
+- Project-specific → `{vault_path}/notes/learnings.md`
+- Global/harness pattern → harness project learnings.md
+- Check for duplicates via `obsidian search` before writing
+
+Format:
+```markdown
+## [LEARN:{tag}] {Short title}
+- **What**: What went wrong or was discovered
+- **So What**: Why this matters
+- **Now What**: What to do instead
+- **Date**: {YYYY-MM-DD}
+```
+
+Vault indexing is automatic.
+
+## Phase 4 — Propose Rule Updates
+
+For findings where a rule SHOULD have blocked the behavior:
+1. Identify which `~/.claude/rules/` file it belongs in
+2. Draft as Invariant (BLOCK) or Convention (WARN)
+3. Present to user with reason. **Do NOT write without approval.**
+4. If declined: log decline in the [LEARN:tag] entry
+
+## Phase 5 — Update claude-progress.json
+
+Append session entry:
+```json
+{
+  "date": "{YYYY-MM-DD}",
+  "summary": "{1-line}",
+  "accomplishments": [],
+  "learn_entries": 0,
+  "rule_proposals": 0,
+  "corrections": 0
+}
+```
+
+## Phase 6 — vault-gc Lightweight Check
+
+Run inline staleness check across all `status.md` files in active projects.
+- Silent if 0 stale
+- One line if 1–2 stale
+- Escalate if 3+ stale
+
+## Phase 7 — Session Health Assessment
+
+| Signal | Threshold | Action |
+|--------|-----------|--------|
+| Corrections from user | >2 | Suggest `/clear` |
+| Scope drift | Any | Note in summary |
+| Same correction repeated | 2+ | Rule proposal mandatory |
+
+## Output Format
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  SESSION RETRO — {today_date}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Summary
+  {bullets}
+
+  Learnings: {n}  |  Rules: {n}  |  Corrections: {n}
+
+  {vault-gc output if non-empty}
+  {/clear suggestion if warranted}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+## Error Handling
+
+| Condition | Action |
+|-----------|--------|
+| Can't detect project | Ask, or write to fallback |
+| `claude-progress.json` missing | Create from template |
+| Vault search fails | Warn only |
+| User declines all proposals | Log declines, proceed |
+
+## Removal Condition
+Remove when session transcripts are parsed automatically and [LEARN:tag] entries generated without Claude.