impulso 0.19.1

package/commands/impulso-directspeech-compress.md

@@ -0,0 +1,137 @@
+---
+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)
+
+---
+
+**User arguments:** $ARGUMENTS

package/commands/impulso-directspeech-help.md

@@ -0,0 +1,33 @@
+---
+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.
+
+---
+
+**User arguments:** $ARGUMENTS

package/commands/impulso-directspeech-stats.md

@@ -0,0 +1,16 @@
+---
+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.
+
+---
+
+**User arguments:** $ARGUMENTS

package/commands/impulso-implement.md

@@ -0,0 +1,86 @@
+---
+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.
+
+---
+
+**User arguments:** $ARGUMENTS

package/commands/impulso-plan.md

@@ -0,0 +1,92 @@
+---
+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.
+
+---
+
+**User arguments:** $ARGUMENTS

package/commands/impulso-ship.md

@@ -0,0 +1,46 @@
+---
+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.
+
+---
+
+**User arguments:** $ARGUMENTS

package/commands/impulso-spec.md

@@ -0,0 +1,106 @@
+---
+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.
+
+---
+
+**User arguments:** $ARGUMENTS

package/commands/impulso-verify.md

@@ -0,0 +1,99 @@
+---
+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.
+
+---
+
+**User arguments:** $ARGUMENTS

package/commands/plannotator-annotate.md

@@ -0,0 +1,47 @@
+---
+description:
+  "Open Plannotator's annotation UI for a markdown file, HTML file, URL, or
+  folder and then respond to the returned annotations."
+---
+
+# Plannotator Annotate
+
+Use when user wants document annotated in Plannotator.
+
+## Protocol
+
+1. Set `TARGET` to the file/URL/folder to annotate. Never empty.
+
+2. Launch plannotator and get the URL:
+
+   ```bash
+   impulso-hub plannotator launch annotate <TARGET>
+   ```
+
+   This returns a JSON line with `url`, `remoteUrl`, `port`, and `pid`.
+   Plannotator runs in the background.
+
+3. **IMMEDIATELY relay URL:** "Open Plannotator at `<URL>` (remote: `<Remote>`).
+   Annotate `<TARGET>`, then tell me when done." WAIT for user to confirm.
+
+4. After user confirms, wait for plannotator to finish and get the decision:
+
+   ```bash
+   impulso-hub plannotator wait
+   ```
+
+   Returns JSON:
+   `{"decision":"approved"|"dismissed"|"annotated","feedback":"..."}`.
+
+5. Apply the decision:
+   - `approved` → acknowledge, proceed.
+   - `dismissed` → session closed, say so, continue.
+   - `annotated` → address the feedback text.
+
+6. Launch timeout (impulso-hub exits 2): check stderr, ask whether to retry.
+
+Run commands yourself. Never ask user to paste shell commands into chat.
+
+---
+
+**User arguments:** $ARGUMENTS