impulso 0.19.1

package/skills/impulso-context-pack/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: impulso-context-pack
+description: >
+  Invoke at task start to build shared codebase context for the current slug.
+  Dispatches scout-writer to explore and write .impulso/work/<slug>/context.md
+  (facts + path:line refs). Idempotent — skips if file exists. Advisory opt-in.
+---
+
+# Impulso Context Pack
+
+Build shared codebase context for the active workspace slug. One-time write;
+downstream agents read `context.md` instead of re-exploring.
+
+## MUST
+
+1. Resolve slug + workspace:
+
+   ```bash
+   SLUG=$(impulso-hub status --json | grep '"slug"' | cut -d'"' -f4)
+   WORKSPACE="$PWD/.impulso/work/$SLUG"
+   CONTEXT_PATH="$WORKSPACE/context.md"
+   ```
+
+2. Check idempotency — if `$CONTEXT_PATH` already exists, report path and stop:
+
+   ```bash
+   test -f "$CONTEXT_PATH" && echo "context.md exists: $CONTEXT_PATH" && exit 0
+   ```
+
+3. Dispatch `scout-writer` (NOT `scout`) with this instruction:
+
+   - Read `$WORKSPACE/spec.md` and `$WORKSPACE/brainstorm.md` (whichever exists)
+     to understand the slug's scope.
+   - Explore the codebase for files, symbols, and constraints relevant to that
+     scope.
+   - Write `$CONTEXT_PATH` in this schema — facts only, `path:line` refs, no
+     recommendations:
+
+     ```
+     # Context — <slug>
+     scope: <one line from spec/brainstorm>
+     ## Relevant files
+     - path:line — fact
+     ## Constraints
+     - <AGENTS.md / spec constraint that bounds implementation>
+     ```
+
+   scout-writer's write guard allows `.impulso/` writes and denies source-tree
+   writes — no extra scoping needed.
+
+4. Report `$CONTEXT_PATH` + one-line fact count (number of `- path:line` entries
+   in `## Relevant files`).

package/skills/impulso-debug/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: impulso-debug
+description: >
+  Standalone debug protocol: establish repro, generate hypotheses, confirm root
+  cause, write regression test, apply fix. No pipeline workspace required.
+---
+
+# Impulso Debug
+
+Standalone debugger protocol. No workspace phases. Repro-first investigation.
+
+## MUST
+
+1. **Repro gate** — do not proceed without a confirmed reproduction:
+
+   - Collect: symptom, environment, steps to reproduce, expected vs actual.
+   - Run repro. Can't reproduce → say so, stop.
+   - Confirm: "Reproduced: \<exact failure\>."
+
+2. **Hypotheses** — generate ≥3 plausible root causes ranked by probability. For
+   each: evidence for/against, cheapest falsification test.
+
+3. **Confirm root cause** — run cheapest falsification tests. Eliminate until
+   one confirmed. State: "Root cause: \<description\>."
+
+4. **Regression test** — write failing test capturing exact bug before fixing.
+   Run via:
+
+   ```bash
+   impulso-hub run-test
+   ```
+
+   Confirm red (non-zero exit). No workspace → run test suite directly.
+
+5. **Fix** — minimal change to pass regression test. No unrelated edits.
+
+6. **Confirm green** — run tests. Confirm all pass.
+
+7. **Report** — ≤15-line status block:
+
+   ```
+   STATUS: DONE|DONE_WITH_CONCERNS|BLOCKED
+   root-cause: <one sentence>
+   fix: <file:line — what changed>
+   regression-test: <file:line>
+   concerns: <none|description>
+   ```

package/skills/impulso-directspeech-compress/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: impulso-directspeech-compress
+description: >
+  Compress natural language memory files (CLAUDE.md, todos, preferences) into
+  Impulso-DirectSpeech format to save input tokens. Preserves all technical
+  substance, code, URLs, and structure. Compressed version overwrites the
+  original file. Human-readable backup saved as FILE.original.md. Trigger:
+  /impulso-directspeech-compress FILEPATH or "compress memory file"
+---
+
+# Impulso-DirectSpeech Compress
+
+## Purpose
+
+Compress natural language files into terse DirectSpeech to reduce input tokens.
+Overwrites original. Backup: `<filename>.original.md`.
+
+## Trigger
+
+`/impulso-directspeech-compress <filepath>` or when user asks to compress a
+memory file.
+
+## Process
+
+1. Scripts in `scripts/` adjacent to this SKILL.md. If not found, search for
+   `scripts/__main__.py`.
+
+2. From the directory containing this SKILL.md, run:
+
+python3 -m scripts <absolute_filepath>
+
+3. CLI will:
+
+- detect file type
+- call Claude to compress
+- validate output
+- errors: cherry-pick fix (targeted, no recompression), retry ≤2 times
+- still failing after 2 retries: report error, leave original untouched
+
+4. Return result to user
+
+## Compression Rules
+
+### Remove
+
+- Articles: a, an, the
+- Filler: just, really, basically, actually, simply, essentially, generally
+- Pleasantries: "sure", "certainly", "of course", "happy to", "I'd recommend"
+- Hedging: "it might be worth", "you could consider", "it would be good to"
+- Redundant phrasing: "in order to" → "to", "make sure to" → "ensure", "the
+  reason is because" → "because"
+- Connective fluff: "however", "furthermore", "additionally", "in addition"
+
+### Preserve EXACTLY (never modify)
+
+- Code blocks (fenced ``` and indented)
+- Inline code (`backtick content`)
+- URLs and links (full URLs, markdown links)
+- File paths (`/src/components/...`, `./config.yaml`)
+- Commands (`npm install`, `git commit`, `docker build`)
+- Technical terms (library names, API names, protocols, algorithms)
+- Proper nouns (project names, people, companies)
+- Dates, version numbers, numeric values
+- Environment variables (`$HOME`, `NODE_ENV`)
+
+### Preserve Structure
+
+- All markdown headings (keep exact heading text, compress body below)
+- Bullet point hierarchy (keep nesting level)
+- Numbered lists (keep numbering)
+- Tables (compress cell text, keep structure)
+- Frontmatter/YAML headers in markdown files
+
+### Compress
+
+- Use short synonyms: "big" not "extensive", "fix" not "implement a solution
+  for", "use" not "utilize"
+- Fragments OK: "Run tests before commit" not "You should always run tests
+  before committing"
+- Drop "you should", "make sure to", "remember to" — just state the action
+- Merge redundant bullets that say the same thing differently
+- Keep one example where multiple examples show the same pattern
+
+CRITICAL RULE: Anything inside `...` must be copied EXACTLY. Do not:
+
+- remove comments
+- remove spacing
+- reorder lines
+- shorten commands
+- simplify anything
+
+Inline code (`...`) must be preserved EXACTLY. Do not modify anything inside
+backticks.
+
+If file contains code blocks:
+
+- Treat code blocks as read-only regions
+- Only compress text outside them
+- Do not merge sections around code
+
+## Pattern
+
+Original:
+
+> You should always make sure to run the test suite before pushing any changes
+> to the main branch. This is important because it helps catch bugs early and
+> prevents broken builds from being deployed to production.
+
+Compressed:
+
+> Run tests before push to main. Catch bugs early, prevent broken prod deploys.
+
+Original:
+
+> The application uses a microservices architecture with the following
+> components. The API gateway handles all incoming requests and routes them to
+> the appropriate service. The authentication service is responsible for
+> managing user sessions and JWT tokens.
+
+Compressed:
+
+> Microservices architecture. API gateway route all requests to services. Auth
+> service manage user sessions + JWT tokens.
+
+## Boundaries
+
+- ONLY compress natural language files (.md, .txt, .typ, .typst, .tex,
+  extensionless)
+- NEVER modify: .py, .js, .ts, .json, .yaml, .yml, .toml, .env, .lock, .css,
+  .html, .xml, .sql, .sh
+- Mixed content (prose + code): compress prose sections only
+- Unsure if code or prose → leave unchanged
+- Backed up as FILE.original.md before overwriting
+- Never compress FILE.original.md (skip it)

package/skills/impulso-directspeech-help/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: impulso-directspeech-help
+description: >
+  Quick-reference card for Impulso-DirectSpeech skills and commands. One-shot
+  display, not a persistent mode. Trigger: /impulso-directspeech-help, "impulso
+  help", "what impulso commands".
+---
+
+# Impulso-DirectSpeech Help
+
+Display reference card when invoked. One-shot — do NOT persist. Output in
+Impulso style.
+
+## Mode
+
+Always active — harness-enforced, every turn. No activation, no off-switch.
+Auto-Clarity drops terseness for security warnings + irreversible actions;
+code/commits/PRs always normal.
+
+## Skills
+
+| Skill                             | Trigger                                 | What it do                                                  |
+| --------------------------------- | --------------------------------------- | ----------------------------------------------------------- |
+| **impulso-directspeech-compress** | `/impulso-directspeech-compress <file>` | Compress .md files to terse prose. Saves ~46% input tokens. |
+| **impulso-directspeech-stats**    | `/impulso-directspeech-stats`           | Lifetime token-savings stats.                               |
+
+## Language
+
+Keep user's language. Portuguese input → Portuguese DirectSpeech. Compress
+style, not language.

package/skills/impulso-directspeech-stats/SKILL.md

@@ -0,0 +1,13 @@
+---
+name: impulso-directspeech-stats
+description: >
+  Show real token usage and estimated savings for the current session. Reads
+  from the session log — no AI estimation. Triggers on
+  /impulso-directspeech-stats.
+---
+
+# Impulso-DirectSpeech Stats
+
+On `/impulso-directspeech-stats`: output token savings in short table — total
+saved, sessions, avg compression ratio. No session log → note stats tracking not
+yet integrated.

package/skills/impulso-implement/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: impulso-implement
+description: >
+  Invoke when the pipeline enters the implement phase: loop every plan task in
+  order, dispatch the right implementer variant per brief, run per-task review,
+  and advance when all tasks are done.
+---
+
+# Impulso Implement
+
+Deterministic state/precondition validation and status `--json` schema v1 are
+owned by `impulso-hub`; this skill retains human interview, dispatch, and
+remediation policy.
+
+Implement phase: sequential task loop (start → brief → dispatch → review) →
+advance.
+
+## MUST
+
+1. Run `impulso-hub status --json`. Confirm `phase === "implement"`. Exit 2 =
+   read stderr, fix, retry.
+
+2. Extract workspace and task list:
+
+   ```bash
+   WORKSPACE=$(impulso-hub workspace-path)
+   TASK_IDS=$(impulso-hub task-ids)
+   ```
+
+3. For each task N in order (sequential — never parallel implementers):
+
+   a. Skip if `impulso-hub status --json` shows task N already
+   `"status":"done"`.
+
+   b. Run:
+
+   ```bash
+   impulso-hub task start <N>
+   BRIEF_PATH=$(impulso-hub brief <N>)
+   REPORT_PATH=$(impulso-hub workspace-path --report <N>)
+   ```
+
+   c. Get the agent variant from the brief and resolve:
+
+   ```bash
+   VARIANT=$(grep '^variant:' "$BRIEF_PATH" | awk '{print $2}')
+   AGENT=$(impulso-hub resolve-agent "$VARIANT")
+   MODEL=$(impulso-hub models --agent "$AGENT")
+   ```
+
+   d. Dispatch implementer (model: `$MODEL`):
+
+   - Brief path: `$BRIEF_PATH`
+   - Report path: `$REPORT_PATH`
+   - Instruction: "Read brief. Write report to report path. Return ≤15-line
+     status block with STATUS, commits, tests, concerns."
+   - On NEEDS_CONTEXT: surface to user, re-dispatch.
+   - On BLOCKED: assess, handle.
+
+   e. Loop: run `impulso-hub task done <N>`. On exit 2 → relay stderr back to
+   same implementer as a fix instruction, re-run until gate passes or BLOCKED.
+
+   f. Generate review package:
+
+   ```bash
+   START_SHA=$(impulso-hub status --field currentTask && impulso-hub status --json | node -e "const d=JSON.parse(require('fs').readFileSync('/dev/stdin','utf8')); process.stdout.write(d.tasks['<N>'].startSha)")
+   DIFF_PATH=$(impulso-hub review-package "$START_SHA" HEAD)
+   REVIEWER_MODEL=$(impulso-hub models --agent reviewer)
+   ```
+
+   g. Dispatch reviewer (model: `$REVIEWER_MODEL`):
+
+   - Brief path: `$BRIEF_PATH`
+   - Report path: `$REPORT_PATH`
+   - Diff path: `$DIFF_PATH`
+   - Instruction: "Review the diff. Return ≤15-line verdict."
+   - Critical/Important findings: dispatch implementer once, re-dispatch
+     reviewer. One fix cycle only.
+
+   h. Proceed to task N+1.
+
+4. After all tasks complete, run `impulso-hub advance`. Exit 2 = read stderr,
+   fix, retry.

package/skills/impulso-plan/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: impulso-plan
+description: >
+  Invoke when the pipeline enters the plan phase: dispatch planner to draft
+  plan.md, run the plannotator-annotate gate, apply feedback, record the marker,
+  and advance.
+---
+
+# Impulso Plan
+
+Deterministic state/precondition validation and status `--json` schema v1 are
+owned by `impulso-hub`; this skill retains human interview, dispatch, and
+remediation policy.
+
+Plan phase: planner drafts plan.md → plannotator annotate gate → record →
+advance.
+
+## Plan task format (planner must follow exactly)
+
+```
+## Task N: <title>
+variant: default|frontend|infra
+model-hint: <haiku|sonnet|opus>
+parallel-safe: yes|no
+
+- [ ] write failing test for <behavior> — verify FAIL
+- [ ] minimal implementation — verify PASS
+
+Interfaces: <exact signatures>
+```
+
+`tdd: false — <justification>` allowed only when no testable surface exists.
+
+## MUST
+
+1. Run `impulso-hub status --json`. Confirm `phase === "plan"`. Exit 2 = read
+   stderr, fix, retry if solvable; surface to user if not.
+
+2. Get planner model and workspace paths:
+
+   ```bash
+   MODEL=$(impulso-hub models --agent planner)
+   PLAN_PATH=$(impulso-hub workspace-path --plan)
+   WORKSPACE=$(impulso-hub workspace-path)
+   SPEC_PATH=$(impulso-hub workspace-path --spec)
+   ```
+
+3. Dispatch planner (model: `$MODEL`):
+
+   - Context paths: `$WORKSPACE/brainstorm.md`, `$SPEC_PATH`
+   - Output path: `$PLAN_PATH`
+   - Instruction: "Read brainstorm.md and spec.md. Draft plan.md at the output
+     path using the exact task format above. Return ≤15-line status block."
+   - On NEEDS_CONTEXT: surface to user, gather, re-dispatch.
+   - On BLOCKED: surface to user. Do not guess.
+
+4. Launch plannotator on the plan:
+
+   ```bash
+   impulso-hub plannotator launch annotate "$PLAN_PATH"
+   ```
+
+5. **IMMEDIATELY relay URL:** "Open Plannotator at \<URL\> (remote: \<Remote\>).
+   Annotate plan.md, then tell me when done." WAIT for user.
+
+   Launch timeout (exit 2) → STOP. Check stderr, ask whether to retry.
+
+6. After user confirms:
+
+   ```bash
+   impulso-hub plannotator wait
+   ```
+
+7. `annotated` → re-dispatch planner (model: `$MODEL`) with:
+
+   - Annotation text and plan.md path: `$PLAN_PATH`
+   - Instruction: "Apply these annotations to plan.md. Maintain task format
+     contract. Overwrite in place. Return ≤15-line status block."
+   - On NEEDS_CONTEXT: surface to user, gather, re-dispatch.
+
+8. Run:
+
+   ```bash
+   impulso-hub record-plannotator plan.md
+   ```
+
+   WARNING: editing plan.md after recording invalidates marker.
+
+9. Run `impulso-hub advance`. Exit 2 = read stderr, satisfy precondition, retry.

package/skills/impulso-ship/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: impulso-ship
+description: >
+  Invoke when the pipeline enters the ship phase: dispatch shipper to create the
+  PR, confirm the PR URL is recorded, and advance to complete the pipeline.
+---
+
+# Impulso Ship
+
+Deterministic state/precondition validation and status `--json` schema v1 are
+owned by `impulso-hub`; this skill retains human interview, dispatch, and
+remediation policy.
+
+Ship phase: dispatch shipper → record PR → advance.
+
+## MUST
+
+1. Run `impulso-hub status --json`. Confirm `phase === "ship"`. Exit 2 = read
+   stderr, fix, retry.
+
+2. Get workspace paths and shipper model:
+
+   ```bash
+   SLUG=$(impulso-hub status --field slug)
+   WORKSPACE=$(impulso-hub workspace-path)
+   MODEL=$(impulso-hub models --agent shipper)
+   ```
+
+3. Dispatch shipper (model: `$MODEL`):
+
+   - Spec path: `$WORKSPACE/spec.md`
+   - Plan path: `$WORKSPACE/plan.md`
+   - Instruction: "Read spec.md and plan.md. Commit staged changes (conventional
+     format), push branch, open PR. Run `impulso-hub record-pr <url>` with the
+     resulting PR URL. Watch CI via
+     `impulso-hub ci-watch <url> [--timeout 600]`. Return ≤15-line status
+     block."
+   - On NEEDS_CONTEXT: surface to user, re-dispatch.
+   - On BLOCKED: surface to user. Do not guess.
+
+4. Confirm PR recorded: check `impulso-hub status --json | grep pr.url`.
+
+5. Run `impulso-hub advance`. Exit 2 = read stderr, satisfy precondition, retry.

package/skills/impulso-spec/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: impulso-spec
+description: >
+  Invoke when the pipeline enters the spec phase: dispatch planner to draft
+  spec.md, impulso-hub spec-review-mode determines route (confirm vs
+  plannotator), execute gate action, advance.
+---
+
+# Impulso Spec
+
+Deterministic state/precondition validation and status `--json` schema v1 are
+owned by `impulso-hub`; this skill retains human interview, dispatch, and
+remediation policy.
+
+Spec phase: planner drafts spec.md → impulso-hub spec-review-mode determines
+route (confirm vs plannotator) → execute the gate-specified action → advance.
+
+## MUST
+
+1. Run `impulso-hub status --json`. Confirm `phase === "spec"`. Exit 2 = read
+   stderr, fix, retry.
+
+2. Get planner model and spec path:
+
+   ```bash
+   MODEL=$(impulso-hub models --agent planner)
+   SPEC_PATH=$(impulso-hub workspace-path --spec)
+   WORKSPACE=$(impulso-hub workspace-path)
+   ```
+
+3. Dispatch planner (model: `$MODEL`):
+
+   - Context path: `$WORKSPACE/brainstorm.md`
+   - Output path: `$SPEC_PATH`
+   - Instruction: "Read brainstorm.md. Draft spec.md at the output path. Return
+     ≤15-line status block."
+   - On NEEDS_CONTEXT: surface to user, gather, re-dispatch.
+   - On BLOCKED: surface to user. Do not guess.
+
+4. Get review mode from gate:
+
+   ```bash
+   impulso-hub spec-review-mode
+   ```
+
+   Parse `mode:` and `lines:` from output.
+
+## Route A: mode=confirm — chat confirmation only
+
+5a. Present spec.md to user in chat. Ask: "Confirm this spec is correct?" On
+confirmation:
+
+    ```bash
+    impulso-hub record-spec-confirmation
+    impulso-hub advance
+    ```
+
+    Done. No Plannotator session.
+
+## Route B: mode=plannotator — Plannotator annotate flow
+
+5b. Launch plannotator on the spec:
+
+    ```bash
+    impulso-hub plannotator launch annotate "$SPEC_PATH"
+    ```
+
+    Returns JSON with `url` and `remoteUrl`.
+
+6b. **IMMEDIATELY relay URL:** "Open Plannotator at \<URL\> (remote:
+\<Remote\>). Annotate spec.md, then tell me when done." WAIT for user.
+
+    Launch timeout (exit 2) → STOP. Check stderr, ask whether to retry.
+
+7b. After user confirms:
+
+    ```bash
+    impulso-hub plannotator wait
+    ```
+
+    Returns `{"decision":"approved"|"dismissed"|"annotated","feedback":"..."}`.
+
+8b. `annotated` → re-dispatch planner with feedback:
+
+    - Annotation feedback text
+    - spec.md path: `$SPEC_PATH`
+    - Instruction: "Apply these annotations to spec.md. Overwrite in place.
+      Return ≤15-line status block."
+    - On NEEDS_CONTEXT: surface to user, gather, re-dispatch.
+
+9b. Run:
+
+    ```bash
+    impulso-hub record-plannotator spec.md
+    ```
+
+    WARNING: editing spec.md after recording invalidates marker. Re-run
+    plannotator session if file changes.
+
+## Advance
+
+10. Run `impulso-hub advance`. Exit 2 = read stderr, satisfy precondition,
+    retry.

package/skills/impulso-verify/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: impulso-verify
+description: >
+  Invoke when the pipeline enters the verify phase: run full test suite and
+  coverage, dispatch branch reviewer, run fix cycle if needed, run
+  plannotator-review gate, record, and advance.
+---
+
+# Impulso Verify
+
+Deterministic state/precondition validation and status `--json` schema v1 are
+owned by `impulso-hub`; this skill retains human interview, dispatch, and
+remediation policy.
+
+Verify phase: tests → coverage → branch review → fix cycle → plannotator-review
+gate → record → advance.
+
+## MUST
+
+1. Run `impulso-hub status --json`. Confirm `phase === "verify"`. Exit 2 = read
+   stderr, fix, retry.
+
+2. Extract workspace:
+
+   ```bash
+   WORKSPACE=$(impulso-hub workspace-path)
+   ```
+
+3. Run full test suite:
+
+   ```bash
+   impulso-hub run-test --full
+   ```
+
+   Non-zero = tests failing. Fix before continuing.
+
+4. Run coverage:
+
+   ```bash
+   impulso-hub run-test --coverage
+   ```
+
+   Non-zero = coverage failing. Fix before continuing.
+
+5. Generate branch review package:
+
+   ```bash
+   BASE=$(impulso-hub merge-base)
+   DIFF_PATH=$(impulso-hub review-package "$BASE" HEAD)
+   REVIEWER_MODEL=$(impulso-hub models --agent reviewer)
+   ```
+
+6. Dispatch reviewer (model: `$REVIEWER_MODEL`) for branch review:
+
+   - Diff path: `$DIFF_PATH`
+   - Instruction: "Branch review: review the full diff from main. Return
+     ≤15-line verdict."
+   - Critical/Important: dispatch implementer once with findings, re-run tests
+     (steps 3–4), re-dispatch reviewer. Once only.
+
+7. When reviewer has **no Critical or Important** findings:
+
+   ```bash
+   impulso-hub record-review-verdict clean
+   ```
+
+   Critical/Important remaining → `impulso-hub record-review-verdict findings`.
+
+8. Run plannotator review:
+
+   ```bash
+   impulso-hub plannotator launch review
+   ```
+
+9. **IMMEDIATELY relay URL:** "Open Plannotator at \<URL\> (remote: \<Remote\>).
+   Review the branch changes, then tell me when done." WAIT for user.
+
+   Launch timeout (exit 2) → STOP. Check stderr, ask whether to retry.
+
+10. After user confirms:
+
+    ```bash
+    impulso-hub plannotator wait
+    ```
+
+11. Feedback → apply fixes, re-run tests (steps 3–4), re-run plannotator review
+    (steps 8–10). LGTM → continue.
+
+12. Record and advance:
+
+    ```bash
+    impulso-hub record-plannotator --review
+    impulso-hub advance
+    ```
+
+    WARNING: committing after recording invalidates marker.