@jamie-tam/forge 6.0.0 → 6.2.0

package/commands/note.md

@@ -0,0 +1,64 @@
+---
+name: note
+description: "Append a one-off research note, brainstorm, or insight to aiwiki/raw/{date}.md with a timestamp. Zero schema, zero friction — capture first, dream consolidates later. Use during Phase 1-2 research, ad-hoc exploration, or any thought worth remembering that doesn't yet fit a typed page (decision/gotcha/convention)."
+---
+
+# /note — Capture to aiwiki/raw
+
+Append the user-supplied text to `aiwiki/raw/{YYYY-MM-DD}.md` under a timestamped header. No schema, no judgment — just capture. The wiki-lint hook fires automatically on save (no-op for raw/ since raw has no schema). `support-dream` consolidates raw entries at phase-close and PreCompact (~85% context), promoting anything that matches a typed schema to `aiwiki/proposed/{dream_id}/` for review.
+
+## Steps
+
+1. **Note text** = everything after `/note ` in the user's invocation. If the argument is empty, ask the user what they'd like to capture and wait for the reply.
+2. **Today's date** = `$(date +%Y-%m-%d)`.
+3. **Target file** = `aiwiki/raw/{date}.md`. Create the directory if needed: `mkdir -p aiwiki/raw`.
+4. **If the file doesn't exist**, start it with: `# Raw notes — {date}` followed by a blank line.
+5. **Append a section**:
+   - Header: `## {HH:MM} — {first ~60 chars of the note, no trailing punctuation}`
+   - Blank line
+   - The full note body
+   - Blank line
+6. **Confirm to the user**: "Captured to `aiwiki/raw/{date}.md`."
+
+## Example
+
+User: `/note Considering Tailwind v4 — oxide engine fast but plugin ecosystem still broken in 2026; revisit in Q3`
+
+Resulting `aiwiki/raw/2026-05-15.md`:
+
+```markdown
+# Raw notes — 2026-05-15
+
+## 14:23 — Considering Tailwind v4 — oxide engine fast but plugin ecosystem
+
+Considering Tailwind v4 — oxide engine fast but plugin ecosystem still broken in 2026; revisit in Q3
+```
+
+## When to use
+
+- During **Phase 1 (concept)** or **Phase 2 (wireframe)** when research or brainstorm yields an insight worth remembering — neither phase auto-captures to aiwiki, so `/note` is the manual hook.
+- During any phase when a thought doesn't yet fit a typed page (it's not yet a decision, not yet a confirmed gotcha, not yet an established convention).
+- When deferring a decision: "considered X, need more info before committing."
+
+## When NOT to use
+
+- The content is a **decision** → write to `aiwiki/decisions/` directly using the decision schema. Future agents read that folder for ADRs; raw notes there won't be retrieved predictably.
+- The content is a **confirmed gotcha** (with reproducible failure mode) → write to `aiwiki/gotchas/` directly so gotcha-hunter can find it.
+- The content is an **established convention** → write to `aiwiki/conventions/` so harden and code-reviewer can enforce it.
+
+`/note` is for the in-between — research, hypotheses, half-formed thoughts that haven't earned a typed page yet. Dream consolidation will promote anything that matures into a typed shape.
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | `aiwiki/` directory (scaffolded by `/setup`) |
+| **Produces** | New or appended `aiwiki/raw/{YYYY-MM-DD}.md` |
+| **Triggers** | `wiki-lint` PostToolUse hook (no-op for raw/) |
+| **Feeds into** | `support-dream` at phase-close and PreCompact — raw entries that match typed schemas get promoted to `aiwiki/proposed/{dream_id}/` for user review |
+
+## Do NOT
+
+- Do NOT edit prior entries. The point is append-only history. If a note turned out wrong, append a correction with the new timestamp.
+- Do NOT structure the note. Plain prose. Schema-fitting is dream's job, not yours.
+- Do NOT use `/note` for things that already fit a typed schema — write the typed page directly instead.

package/commands/{task-force.md → parallel.md}

@@ -1,12 +1,12 @@
 ---
-name: task-force
-description: "Dispatch a parallel task-force per item in a user-provided punch list. Phase-aware sizing (light teams in prototype phases, full crew in production). Routes command-shaped items (features, bugfixes, refactors) to their owning commands. Include !max (or --full-power) in your prompt to force full-crew production teams regardless of detected phase."
+name: parallel
+description: "Dispatch parallel agents per item in a user-provided punch list. Phase-aware sizing (light teams in prototype phases, full crew in production). Routes command-shaped items (features, bugfixes, refactors) to their owning commands. Include !max (or --full-power) in your prompt to force full-crew production teams regardless of detected phase."
 argument-hint: "task1; task2; task3 (or numbered/bulleted list); append !max to force full crew"
 ---
 
-# /task-force
+# /parallel
 
-Run a parallel ad-hoc task-force dispatcher over a punch list of independent tasks.
+Run a parallel ad-hoc dispatcher over a punch list of independent tasks.
 
 ## When to use
 
@@ -25,26 +25,26 @@ Run a parallel ad-hoc task-force dispatcher over a punch list of independent tas
 
 ## Process
 
-REQUIRED SUB-SKILL: Use **support-task-force** to:
+REQUIRED SUB-SKILL: Use **support-parallel** to:
 1. Run Codex consent (one-time per run, per `protocols/codex.md`)
 2. Detect repo phase (prototype vs production) from active manifest or repo state
 3. Parse the task list (numbered, bulleted, or semicolon-separated argument)
 4. Classify each task by type (dev / research / debug / docs / review / security / quick / complex / command-shaped)
-5. Route command-shaped items to their owning commands (do NOT dispatch task-forces for them)
+5. Route command-shaped items to their owning commands (do NOT dispatch parallel runs for them)
 6. Assemble a team per task, sized by task type AND phase mode
-7. Dispatch all task-forces in parallel (background subagents)
+7. Dispatch all per-task teams in parallel (background subagents)
 8. Aggregate per-task verdicts with Claude+Codex consensus check
 9. Surface a run-summary with conflicts highlighted
 
 ## Arguments
 
 Either:
-- Pass the list directly: `/task-force update README; explore caching options; add test for parser`
-- Or pass a numbered/bulleted list in the next prompt after invoking `/task-force` bare
+- Pass the list directly: `/parallel update README; explore caching options; add test for parser`
+- Or pass a numbered/bulleted list in the next prompt after invoking `/parallel` bare
 
 ## Output
 
-`.forge/task-force/{run-id}/` containing:
+`.forge/parallel/{run-id}/` containing:
 - `codex.yaml` — Codex consent choice
 - `tasks.yaml` — task classifications
 - `task-{n}/{role}.md` — per-agent output
@@ -63,7 +63,7 @@ Either:
 ### Standard (phase-aware sizing)
 
 ```
-/task-force
+/parallel
 1. Update README with new install steps
 2. Explore options for adding a /status command
 3. Add unit test for parser edge cases
@@ -84,7 +84,7 @@ In prototype phase, the same list dispatches ~5 agents (light templates, no Code
 ### Force full power (`!max` override)
 
 ```
-/task-force !max
+/parallel !max
 1. Update README with new install steps
 2. Add helper function for date parsing
 3. Investigate why CI is flaky on test 17
@@ -100,11 +100,11 @@ Use `!max` (short form) or `--full-power` (canonical form) when prototype code i
 
 ## Manifest
 
-This command does NOT create a `.forge/work/{type}/{name}/` manifest — task-force runs are not phase-gated. State lives in `.forge/task-force/{run-id}/` only.
+This command does NOT create a `.forge/work/{type}/{name}/` manifest — `/parallel` runs are not phase-gated. State lives in `.forge/parallel/{run-id}/` only.
 
-If an active feature/bugfix manifest exists, the task-force run-id is appended to its current phase as `task-force-runs: [...]` for audit.
+If an active feature/bugfix manifest exists, the parallel run-id is appended to its current phase as `parallel-runs: [...]` for audit.
 
 ## See also
 
-- `skills/support-task-force/SKILL.md` — full process documentation
+- `skills/support-parallel/SKILL.md` — full process documentation
 - `/feature`, `/bugfix`, `/refactor` — for command-shaped work that this skill refuses to swallow

package/commands/resume.md

@@ -10,7 +10,7 @@ Resume a paused work item without restarting completed phases.
 
 ## Scope
 
-Resumes an existing in-flight work item by reading its manifest and re-entering its owning command (`/feature`, `/greenfield`, `/bugfix`, `/hotfix`, `/refactor`) at the first unfinished phase. Does NOT create new work items, modify gate state, re-run already-passed gates, or abort/escalate work. Invoke after a session break, after a manifest update, or whenever the user wants to continue paused work.
+Resumes an existing in-flight work item by reading its manifest and re-entering its owning command (`/feature`, `/greenfield`, `/bugfix`, `/hotfix`, `/refactor`) at the first unfinished phase. Does NOT create new work items, modify gate state, re-run already-passed gates, or escalate work. Invoke after a session break, after a manifest update, or whenever the user wants to continue paused work.
 
 ## Input
 
@@ -19,7 +19,7 @@ Accept `type/name` when provided, such as `feature/add-payments`. If omitted, ru
 ## Steps
 
 1. Read `.forge/work/{type}/{name}/manifest.yaml`.
-2. If `status` is `completed`, `abandoned`, or `escalated`, do not resume. Surface the status and any `successor_path`.
+2. If `status` is `completed` or `escalated`, do not resume. Surface the status and any `successor_path`.
 3. Identify the last completed phase and the first incomplete phase using the same gate-skip rules as the owning command.
 4. Invoke the owning command (`/feature`, `/greenfield`, `/bugfix`, `/hotfix`, or `/refactor`) with the work item name and instruct it to resume from the manifest.
 5. Do not recreate manifests, delete files, or rerun phases whose gates already passed.

package/commands/setup.md

@@ -96,34 +96,35 @@ After confirmation, fill both project docs. Show the filled content for review b
 STOP. Present the filled CLAUDE.md and AGENTS.md content to the user for review before writing. Do NOT write files without user confirmation.
 </GATE>
 
-## Step 2a: Configure Gate Enforcement Mode
+## Step 2a: Apply Gate Enforcement Mode
 
 `npx @jamie-tam/forge init` installs PreToolUse hooks that block manifest `gate-passed: true` edits unless telemetry shows the matching skill was invoked via the Skill tool. Useful for production-grade work; high-friction for prototype iteration where most phases are explicitly skipped.
 
-**Default suggestion** (computed from Step 2 profile):
-- If signals match **prototype mode** (path under `pocs/`, `package.json` `"private": true` with no CI, no `aiwiki/architecture/`): suggest **disable**
-- If signals match **production mode** (CI configured, tests present, codified architecture exists or imminent): suggest **keep enabled**
+**Apply automatically based on detected mode** (no prompt — the user has not yet seen a gate fire and can't reasonably decide upfront; setup chooses the mode-appropriate default and tells the user how to change it later).
 
-Ask the user:
+Detect from the Step 2 profile:
 
-```
-Gate enforcement (PreToolUse hooks that block manifest gate-passed edits without skill-invocation telemetry):
-
-Suggested for this project: <KEEP ENABLED | DISABLE>
-
-  • Keep enabled — production-grade discipline; manifests cannot lie about gate state
-  • Disable     — prototype iteration; faster loop, telemetry still recorded for retrospective audit
-
-Choice? [Y]es (keep enabled) / [d]isable / [k]eep enabled regardless of suggestion
-```
+| Mode signal | Decision |
+|---|---|
+| Working under `pocs/`, OR `package.json` has `"private": true` with no CI configured, OR `aiwiki/architecture/` is empty/missing | **Disable** — prototype iteration; faster loop |
+| CI configured, tests present, codified architecture exists or imminent | **Keep enabled** — production discipline; manifests cannot lie about gate state |
 
 **On "disable"**: remove the two gate-enforcer matcher entries from `.claude/settings.local.json` (the entries with `matcher: Edit` or `matcher: Write` whose command invokes `.claude/hooks/scripts/gate-enforcer.sh`). The file is gitignored so this is a local-only change. Keep the PostToolUse telemetry hook — telemetry is still recorded for retrospective audit; only the blocking is removed.
 
 **On "keep enabled"**: leave settings.local.json as installed.
 
-Tell the user: "Gate enforcement <enabled / disabled>. To toggle later, edit `.claude/settings.local.json` — see `hooks/hooks.json` in the forge repo for the canonical entries."
+**Then tell the user, plainly:**
+
+```
+Gate enforcement: <enabled | disabled>
+  Reason: <mode signal that triggered it>
+  To change: remove or restore the two gate-enforcer PreToolUse entries in
+  .claude/settings.local.json (canonical entries in hooks/hooks.json).
+  First time you hit a real gate-passed edit and want to opt in (or out),
+  surface the toggle then — no upfront commitment.
+```
 
-Note in the manifest or session memo what was chosen, so future sessions don't have to re-detect.
+Note in the manifest or session memo what was applied, so future sessions don't have to re-detect.
 
 ## Step 3: Create .forge Directory
 

package/commands/status.md

@@ -9,12 +9,12 @@ List active work items from `.forge/work/` without modifying files.
 
 ## Scope
 
-Reports in-flight `.forge/work/` items and their current phase. Read-only — does not modify manifests, files, or wiki. Does NOT resume work, route between commands, or judge whether a stalled item should be aborted. Invoke when the user asks "what's in flight?", before `/resume` (to pick a target), or before `/abort` (to confirm which item).
+Reports in-flight `.forge/work/` items and their current phase. Read-only — does not modify manifests, files, or wiki. Does NOT resume work or route between commands. Invoke when the user asks "what's in flight?" or before `/resume` (to pick a target).
 
 ## Steps
 
 1. Find manifests at `.forge/work/*/*/manifest.yaml`.
-2. Exclude items whose `status` is `completed`, `abandoned`, or `escalated`.
+2. Exclude items whose `status` is `completed` or `escalated`.
 3. For each remaining item, infer the current phase from the first phase or gate that is not complete, locked, skipped, or not-applicable. Prefer explicit fields such as `build.current_phase` when present.
 4. Print a table:
 

package/commands/wrap.md

@@ -0,0 +1,130 @@
+---
+name: wrap
+description: "Capture and finalize the current Claude session. Writes ## Files touched / ## Decisions made / ## Gotchas surfaced / ## Open questions / ## Next steps into aiwiki/sessions/{date}-{session_id_short}.md, then sets status: done. Use at the natural end of a working session so the next session-start hook can surface a meaningful handoff. Optional argument: a one-line focus statement (otherwise inferred from the active manifest)."
+---
+
+# /wrap — Capture and finalize the current session
+
+Finalize this Claude session's handoff artifact. Writes the index sections (Files touched / Decisions / Gotchas / Open questions / Next steps) into `aiwiki/sessions/{date}-{session_id_short}.md` so the next session-start hook can surface a meaningful handoff.
+
+**Distinct from `/dream`:** `/wrap` captures *this session's* knowledge (what was worked on, what was decided). `/dream` consolidates *the whole aiwiki* (merges duplicates, promotes raw → typed). The two can be run sequentially at session end (`/wrap` first, then `/dream`) but they answer different questions.
+
+## Steps
+
+1. **Determine session file path.**
+   - Read `session_id` from the most recent SessionStart context (Claude Code provides this in the hook payload; if running standalone, ask the user or read from `aiwiki/sessions/*.md` mtime).
+   - Path: `aiwiki/sessions/{ISO-date}-{session_id_short7}.md` (the same path pre-compact would have used). If the file already exists (created by pre-compact), append to it. If not, create it lazily here.
+
+2. **Determine focus.**
+   - If `/wrap <focus statement>` was supplied, use that.
+   - Else: read the active work item from `.forge/work/*/*/manifest.yaml` where `status: in-progress`. Focus = `{type}/{name}` (e.g. `feature/wire-dream`).
+   - Else: ask the user "What was this session about?" — one-line answer.
+
+3. **Read the session file** (if it already has content from pre-compact).
+   - The `## Checkpoints` section stays as-is — that's event log, not user-facing summary.
+   - The index sections (`## Files touched`, etc.) are what you fill.
+
+4. **Capture `## Files touched`.**
+   - Run `git diff --name-only $(git merge-base HEAD main)..HEAD` (or `HEAD~10..HEAD` for non-branch work) to find files changed during the session.
+   - For each: cite as `[path](path:line)` if a specific line range was the focus; else `[path](path)`.
+   - LINT will auto-fill `@<sha7>` on save.
+   - Skip generated files, dependency lockfiles, build artifacts.
+
+5. **Capture `## Decisions made`.**
+   - List ADRs in `aiwiki/decisions/` written or modified during this session.
+   - Format: `- [decision-NNNN: short title](aiwiki/decisions/NNNN-slug.md)`.
+   - If none were written but a decision-worthy choice was made conversationally, note: "DEFERRED: {one-line description} — should become an ADR but wasn't written this session."
+
+6. **Capture `## Gotchas surfaced`.**
+   - List gotchas in `aiwiki/gotchas/` created or updated this session.
+   - Same link format.
+   - If a gotcha was hit but not captured, note it as DEFERRED.
+
+7. **Capture `## Open questions`.**
+   - List raw notes in `aiwiki/raw/{today}.md` that represent unresolved questions (entries starting with "TBD", "open", "?", or that were /note'd as questions).
+   - Format: `- [HH:MM question title](aiwiki/raw/{date}.md#anchor)`.
+   - If no /note questions were captured but threads are open, list them as bare bullets.
+
+8. **Capture `## Next steps`.**
+   - 2-5 bullets: what the next session should do.
+   - Each bullet should reference a file/manifest/issue. No vague "continue working on X."
+   - Examples:
+     - "Resume `feature/wire-dream` at Phase 6 (slice graph in manifest) — first slice: `wire-pre-compact-hook`."
+     - "Review pending dream `aiwiki/proposed/2026-05-18-1742-manual/` before next phase."
+     - "Address open question on token rotation policy — see `aiwiki/raw/2026-05-18.md#14-23`."
+
+9. **Update frontmatter.**
+   - Set `focus: {focus}` (from Step 2).
+   - Set `status: done`.
+   - Set `date_end: {today ISO date}`.
+   - Set `last_commit: {git rev-parse --short HEAD}` if in a git repo with commits.
+
+10. **Confirm with the user.**
+    - Surface the drafted session file content.
+    - Ask: "Save this as your session handoff?" — yes / edit / skip.
+    - If edit: take inline edits, re-render, ask again.
+    - If skip: leave the file's `status: active` (next session-start will surface it as unfinalized).
+
+11. **Save and lint.**
+    - Write the file.
+    - `wiki-lint` runs automatically on save (PostToolUse hook).
+    - If lint surfaces warnings (missing citations, stale `@<sha7>`, etc.), address before considering /wrap complete.
+
+12. **Suggest follow-ups.**
+    - If `aiwiki/raw/{today}.md` has unconsolidated entries, suggest: "You have N raw notes from this session — consider `/dream raw` to consolidate before next session."
+    - If a pending dream proposal exists in `aiwiki/proposed/`, surface: "N pending dream proposals — review via `forge wiki ui` before next session."
+
+## Example
+
+```
+User: /wrap
+
+Agent: Session 2026-05-18-7e8a3f2 (focus: feature/wire-dream).
+       Drafted handoff with:
+         - 11 files touched (skills/, hooks/, commands/, templates/)
+         - 1 decision (consolidate notepad → sessions/)
+         - 0 new gotchas this session
+         - 2 open questions
+         - 4 next-step bullets
+
+       [Renders the proposed file content]
+
+       Save?
+
+User: yes
+
+Agent: Saved aiwiki/sessions/2026-05-18-7e8a3f2.md (status: done).
+       Suggestion: 3 raw notes from /note today — consider /dream raw to
+       consolidate before next session.
+```
+
+## When to use
+
+- **At the natural end of a working session** before exiting Claude Code. Even a 30-second wrap-up preserves the handoff signal.
+- **Before a long break** (overnight, end of day). The next session-start surfaces this file so you don't lose context.
+- **Before a major context shift** (switching to a different feature mid-day). Wrap the current focus, then start fresh.
+- **After a phase locks** if the natural pause is also a session end. (Phase-close already triggers a dream — `/wrap` is the complementary capture for what *you* did, while dream consolidates the *wiki state*.)
+
+## When NOT to use
+
+- **Trivial sessions** (a single read, a one-line edit). No handoff signal — skip /wrap and let the next session-start surface "no recent session" (silence is fine).
+- **Mid-task interruptions** where you'll be right back. /wrap is for genuine session boundaries.
+- **As a substitute for typed-page writes.** Decisions belong in `aiwiki/decisions/` directly; gotchas in `aiwiki/gotchas/`. /wrap is the *index* of what was written elsewhere — it doesn't replace writing the artifacts themselves.
+- **As a substitute for `/dream`.** /wrap captures this session's work; /dream consolidates the whole aiwiki. Use both at the right times.
+
+## I/O Contract
+
+| Field | Value |
+|---|---|
+| **Requires** | `aiwiki/sessions/` (scaffolded by `/setup`), Claude Code's hook context for `session_id` (or interactive fallback) |
+| **Produces** | `aiwiki/sessions/{date}-{session_id_short}.md` with index sections filled and `status: done` |
+| **Triggers** | `wiki-lint` PostToolUse hook on save |
+| **Feeds into** | `session-start.sh` (next session reads it), `support-dream` (refines on next dream cycle) |
+
+## Do NOT
+
+- Do NOT auto-fire `/dream` from inside `/wrap`. The two are separate concerns; user decides which to run. /wrap can SUGGEST /dream when raw notes accumulated, but does not invoke it.
+- Do NOT overwrite the `## Checkpoints` section if pre-compact wrote to it during the session — that's append-only event log, preserved as-is.
+- Do NOT write vague prose. Index of links, not narrative. Future sessions follow the links to actual artifacts.
+- Do NOT capture every file diff. Skip dependency lockfiles, build artifacts, anything ≤2 lines of cosmetic change. Index the meaningful work.
+- Do NOT set `status: done` if the user said "skip" at Step 10 — leave `status: active` so the next session-start surfaces it.