open/ktg-plugin-marketplace
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity Actions

feat(ultraplan-local): Spor 3 — semantic plan-critic, examples, CC features, security docs

Browse source 
- agents/plan-critic.md: rule #7 split into literal blockers (TBD/TODO/FIXME)
  + semantic rubric with 8 deferred-decision tests; calibrated against the
  5-phrase corpus from the v3.1.0 quality brief
- hooks/hooks.json: rebuilt from corrupted state; valid JSON, registers
  PreToolUse(Bash,Write), UserPromptSubmit, PostToolUse(Bash), PreCompact
- hooks/scripts/session-title.mjs: NEW — sets ultra:<cmd>:<slug> session
  title for ultra commands (CC v2.1.94+)
- hooks/scripts/post-bash-stats.mjs: NEW — appends duration_ms per Bash
  call to ultraexecute-stats.jsonl (CC v2.1.97+)
- SECURITY.md: NEW — Forgejo private-issue reporting, supported = current
  minor only, scope = 4 hooks + denylist, hardening recommendations
- docs/architect-bridge-test.md: NEW — manual smoke checklist for the
  ultraplan ↔ ultra-cc-architect bridge
- examples/01-add-verbose-flag/: NEW — calibrated end-to-end (brief +
  research + plan + progress.json) for fork-er onramp; all four artifacts
  pass their validators
- README.md: + Extending the plugin, + Headless multi-session tuning
  (MCP_CONNECTION_NONBLOCKING), + Session titles, + Per-step timing,
  + disableSkillShellExecution recommendation
- CLAUDE.md: documents session-title.mjs and post-bash-stats.mjs
- root README.md: v3.1.0 entry expanded with Spor 2+3 deliverables

CC features adopted: F8, F9, F12 implemented; F3 implemented as Bash
PostToolUse logger; F2 (hook 'if'-field scoping) deferred — universal
protection beats reduced-scope protection for blocked commands.

Tests: 109/109 green.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
Kjell Tore Guttormsen 2026-05-01 06:28:44 +02:00
commit 9ecd225018
15 changed files with 1170 additions and 59 deletions
Download patch file Download diff file Expand all files Collapse all files

56
plugins/ultraplan-local/examples/01-add-verbose-flag/REGENERATED.md Normal file
View file

@ -0,0 +1,56 @@
# Regeneration log — 01-add-verbose-flag
| Field | Value |
|-------|-------|
| Last regenerated | 2026-05-01 |
| ultraplan-local version | 3.1.0 |
| Claude Code version | ≥ 2.1.105 (PreCompact-hook) |
| Source brief author | Hand-calibrated example, not LLM-generated |
| Plan author | Hand-calibrated to demonstrate plan_version 1.7 schema + manifest YAML |
## What this is
A complete walk-through of the four-stage pipeline for one realistic
small task: adding a `--verbose` flag to a hypothetical `small-auth`
CLI parser. Every artifact is hand-calibrated, not LLM-generated, so
fork-ers can study the *shape* without worrying about whether an
LLM hallucinated something.
## What "regenerate" means
If the artifact format changes (frontmatter schema, manifest YAML
keys, progress.json version), this example needs to be re-built so
fork-ers don't learn an obsolete shape.
Triggers for regeneration:
- `plan_version` bumps
- Frontmatter schema additions to `brief.md` or `research/*.md`
- New required keys in manifest YAML
- `progress.json` schema bump beyond `schema_version: "1"`
When regenerating: do **not** run an actual LLM-driven pipeline against
this brief. Hand-calibrate against the new schema so the example stays
deterministic and reviewable.
## Project assumed
A fictional `small-auth` CLI with this layout:
```
small-auth/
├── package.json
├── src/
│ ├── cli.mjs # 80-line argv parser (hand-rolled)
│ └── commands/
│ ├── login.mjs
│ ├── logout.mjs
│ ├── whoami.mjs
│ ├── token-refresh.mjs
│ ├── users-list.mjs
│ └── users-create.mjs
└── tests/ # 24 tests, node:test
```
This project is **not** in the plugin repo. The example artifacts
reference it as if it were the cwd of an `/ultraexecute-local` run.

55
plugins/ultraplan-local/examples/01-add-verbose-flag/brief.md Normal file
View file

@ -0,0 +1,55 @@
---
type: ultrabrief
brief_version: 1.0
slug: add-verbose-flag
task: Add a --verbose flag to the small-auth CLI parser
research_topics: 1
research_status: complete
brief_quality: ready
created: 2026-05-01
---
# Add `--verbose` flag to small-auth CLI
## Intent
The `small-auth` CLI parser has six commands (`login`, `logout`, `whoami`,
`token-refresh`, `users-list`, `users-create`) and currently emits only
final results — no progress, no timings, no internal step trace. Operators
debugging slow `token-refresh` calls or mis-routed `users-list` queries
have no signal between "started" and "finished".
We want a `--verbose` flag that, when passed, prints structured progress
lines to stderr without changing stdout output. Stdout stays the
machine-parseable contract; stderr becomes the human-readable trace.
## Goal
Add a single `--verbose` boolean flag, recognized by all six commands,
that emits one stderr line per internal step. No other behavioral
changes. The default (`--verbose` absent) produces output byte-identical
to today's CLI.
## Success Criteria
- `small-auth login --verbose alice` exits 0 and writes ≥ 3 stderr lines
prefixed `[verbose]` covering: argument parse, credential lookup,
session-token issue.
- `small-auth login alice` (no flag) writes exactly the same stdout as
before this change — verified by golden-file diff against
`tests/golden/login.stdout`.
- `--verbose` works in any position: `small-auth --verbose login alice`,
`small-auth login --verbose alice`, `small-auth login alice --verbose`.
- `--verbose` short form is `-v`. `-vv` is **not** recognized — only one
level. Document this in `--help`.
- All six commands accept the flag without rejection. Commands that have
no internal steps to trace (`whoami`) still accept the flag silently.
- Existing 24 tests in `tests/` continue to pass. Two new tests added:
one stdout-stability test, one stderr-content test for `login`.
## Out of scope
- Log levels beyond on/off (no `--debug`, `--trace`).
- Structured JSON logging — stderr stays plain text in this iteration.
- Logging configuration via env vars or config file.
- Any command other than the six listed.

251
plugins/ultraplan-local/examples/01-add-verbose-flag/plan.md Normal file
View file

@ -0,0 +1,251 @@
# Add `--verbose` flag to small-auth CLI
plan_version: 1.7
> **Plan quality: A** (92/100) — APPROVE
>
> Generated by ultraplan-local v3.1.0 on 2026-05-01.
## Context
The `small-auth` CLI has six commands and emits only final results; no
progress, no internal step trace. Operators debugging slow `token-refresh`
or mis-routed `users-list` calls have no signal between "started" and
"finished". This plan adds a `--verbose` / `-v` flag that, when set,
emits structured progress lines to stderr without changing stdout. The
default path stays byte-identical.
This is a textbook minimal-scope addition: the parser is small,
centralized, and already supports global flags.
## Architecture Diagram
```mermaid
graph TD
subgraph "Changes in this plan"
cli["src/cli.mjs<br/>parse globalFlags"]
ctx["ctx object<br/>+ verbose: boolean"]
login["src/commands/login.mjs<br/>+ 3 verbose calls"]
token["src/commands/token-refresh.mjs<br/>+ 4 verbose calls"]
userlist["src/commands/users-list.mjs<br/>+ 2 verbose calls"]
usercreate["src/commands/users-create.mjs<br/>+ 3 verbose calls"]
logout["src/commands/logout.mjs<br/>+ 2 verbose calls"]
whoami["src/commands/whoami.mjs<br/>(accepts flag, no traces)"]
help["src/cli.mjs<br/>--help text"]
tests["tests/cli-verbose-flag.test.mjs<br/>tests/cli-no-verbose-stability.test.mjs"]
cli --> ctx
ctx --> login
ctx --> token
ctx --> userlist
ctx --> usercreate
ctx --> logout
ctx --> whoami
cli --> help
login --> tests
end
```
## Codebase Analysis
- **Tech stack:** Node.js ≥ 18, no external runtime dependencies, `node:test` for tests
- **Key patterns:** hand-rolled argv parser, two-pass extract (globals → command), handler contract `run(positional, flags, ctx)`
- **Relevant files:** `src/cli.mjs`, `src/commands/{login,logout,whoami,token-refresh,users-list,users-create}.mjs`, `tests/`
- **Reusable code:** existing `[error]` stderr pattern at `src/cli.mjs:67` — mirror it for `[verbose]`
- **External tech:** none
- **Recent git activity:** parser last changed in commit `ab1c2d3` (added `--version`); pattern still current
## Research Sources
*Internal research only — see `research/01-cli-parser-conventions.md`.*
## Implementation Plan
Each step targets 1–2 files and one focused change. TDD structure: test
or stability harness comes before behavior change.
### Step 1: Capture golden stdout for stability test
- **Files:** `tests/golden/login.stdout` (new file), `tests/golden/whoami.stdout` (new file), `tests/golden/users-list.stdout` (new file)
- **Changes:** Run current CLI for three representative commands, save stdout byte-for-byte. Use `node src/cli.mjs login alice > tests/golden/login.stdout` and similar.
- **Verify:** `wc -c tests/golden/*.stdout` → expected: each file > 0 bytes
- **Checkpoint:** `git commit -m "test(small-auth): capture pre-change golden stdout for verbose-flag stability"`
- **On failure:** revert files; do not proceed. Likely cause: CLI itself broken — investigate before continuing.
- **Manifest:**
```yaml
manifest:
expected_paths:
- tests/golden/login.stdout
- tests/golden/whoami.stdout
- tests/golden/users-list.stdout
min_file_count: 3
commit_message_pattern: "^test\\(small-auth\\): capture"
bash_syntax_check: []
forbidden_paths: []
must_contain: []
```
### Step 2: Add stability test (must FAIL initially — verbose not yet wired)
- **Files:** `tests/cli-no-verbose-stability.test.mjs` (new file)
- **Changes:** Three subtests, one per golden file. Each runs `node src/cli.mjs <cmd> ...` and asserts stdout `===` `readFileSync('tests/golden/<cmd>.stdout')`. The test should PASS today (no behavior change yet) — it's the canary for step 5 onwards.
- **Verify:** `node --test tests/cli-no-verbose-stability.test.mjs` → expected: 3 pass
- **Checkpoint:** `git commit -m "test(small-auth): stdout stability harness for verbose-flag work"`
- **On failure:** if subtests fail, the goldens are wrong — re-run step 1.
- **Manifest:**
```yaml
manifest:
expected_paths:
- tests/cli-no-verbose-stability.test.mjs
min_file_count: 1
commit_message_pattern: "^test\\(small-auth\\): stdout stability"
bash_syntax_check: []
forbidden_paths: []
must_contain:
- path: tests/cli-no-verbose-stability.test.mjs
pattern: "tests/golden/login\\.stdout"
```
### Step 3: Extend parser to recognize `--verbose` and `-v`
- **Files:** `src/cli.mjs`
- **Changes:** At `src/cli.mjs:34` (alias table) add `'-v': '--verbose'`. At `src/cli.mjs:48` (globalFlags loop) add `'--verbose'` case that sets `globalFlags.verbose = true`. Default the field to `false`. The flag is consumed (removed from argv) like `--help` and `--version`.
- **Verify:** `node src/cli.mjs --verbose login alice 2>&1 | head -1` → expected: no parse error
- **Checkpoint:** `git commit -m "feat(cli): recognize --verbose / -v as global flag"`
- **On failure:** revert `src/cli.mjs`; rerun stability test to confirm clean baseline.
- **Manifest:**
```yaml
manifest:
expected_paths:
- src/cli.mjs
min_file_count: 1
commit_message_pattern: "^feat\\(cli\\): recognize --verbose"
bash_syntax_check: []
forbidden_paths: []
must_contain:
- path: src/cli.mjs
pattern: "globalFlags\\.verbose"
```
### Step 4: Pass `verbose` into handler `ctx`
- **Files:** `src/cli.mjs`
- **Changes:** At `src/cli.mjs:62` (ctx construction) add `verbose: globalFlags.verbose` to the ctx literal. No handler changes yet.
- **Verify:** `node --test tests/cli-no-verbose-stability.test.mjs` → expected: 3 pass (handlers ignore the new field for now)
- **Checkpoint:** `git commit -m "feat(cli): thread verbose into command handler ctx"`
- **On failure:** stability tests fail → ctx mutation broke something. Bisect by reverting and adding back one line at a time.
- **Manifest:**
```yaml
manifest:
expected_paths:
- src/cli.mjs
min_file_count: 1
commit_message_pattern: "^feat\\(cli\\): thread verbose"
bash_syntax_check: []
forbidden_paths: []
must_contain:
- path: src/cli.mjs
pattern: "verbose: globalFlags\\.verbose"
```
### Step 5: Wire verbose output in `login`, `token-refresh`, `users-list`, `users-create`, `logout`
- **Files:** `src/commands/login.mjs`, `src/commands/token-refresh.mjs`, `src/commands/users-list.mjs`, `src/commands/users-create.mjs`, `src/commands/logout.mjs`
- **Changes:** At each internal step (3 for login, 4 for token-refresh, 2 for users-list, 3 for users-create, 2 for logout — 14 call sites total), add `if (ctx.verbose) ctx.stderr.write(\`[verbose] <step description>\\n\`);`. Step descriptions per file:
- login: "parsing argv", "credential lookup", "issuing session token"
- token-refresh: "parsing argv", "validating refresh token", "rotating session token", "persisting new token"
- users-list: "parsing argv", "querying user store"
- users-create: "parsing argv", "validating input", "writing user record"
- logout: "parsing argv", "invalidating session token"
- **Verify:** `node --test tests/cli-no-verbose-stability.test.mjs` → expected: 3 pass (stdout unchanged when flag absent)
- **Checkpoint:** `git commit -m "feat(commands): emit verbose stderr trace for 5 commands"`
- **On failure:** stability tests fail → likely a stray `console.log` or `ctx.stdout.write` instead of `ctx.stderr.write`. Re-grep all five files for `stdout` mentions added in this step.
- **Manifest:**
```yaml
manifest:
expected_paths:
- src/commands/login.mjs
- src/commands/token-refresh.mjs
- src/commands/users-list.mjs
- src/commands/users-create.mjs
- src/commands/logout.mjs
min_file_count: 5
commit_message_pattern: "^feat\\(commands\\): emit verbose"
bash_syntax_check: []
forbidden_paths: []
must_contain:
- path: src/commands/login.mjs
pattern: "ctx\\.verbose"
- path: src/commands/token-refresh.mjs
pattern: "ctx\\.verbose"
```
### Step 6: Add verbose-content test for `login`
- **Files:** `tests/cli-verbose-flag.test.mjs` (new file)
- **Changes:** Single test: spawn `node src/cli.mjs login --verbose alice`, capture stderr, assert exit 0, assert stderr contains all three expected verbose lines: "[verbose] parsing argv", "[verbose] credential lookup", "[verbose] issuing session token", in that order.
- **Verify:** `node --test tests/cli-verbose-flag.test.mjs` → expected: 1 pass
- **Checkpoint:** `git commit -m "test(small-auth): assert --verbose emits expected stderr trace"`
- **On failure:** if assertion misses a line, check step 5 for typos in the `[verbose]` strings; if exit code != 0, check that login still works without verbose (regression).
- **Manifest:**
```yaml
manifest:
expected_paths:
- tests/cli-verbose-flag.test.mjs
min_file_count: 1
commit_message_pattern: "^test\\(small-auth\\): assert --verbose"
bash_syntax_check: []
forbidden_paths: []
must_contain:
- path: tests/cli-verbose-flag.test.mjs
pattern: "\\[verbose\\] credential lookup"
```
### Step 7: Update `--help` text
- **Files:** `src/cli.mjs`
- **Changes:** At the help-text constant (`src/cli.mjs:78`), add a line under "Global flags": ` -v, --verbose emit per-step trace to stderr (single level only)`.
- **Verify:** `node src/cli.mjs --help | grep -E "verbose"` → expected: 1 line containing "emit per-step trace"
- **Checkpoint:** `git commit -m "docs(cli): document --verbose / -v in --help text"`
- **On failure:** revert just the constant; help text isn't load-bearing.
- **Manifest:**
```yaml
manifest:
expected_paths:
- src/cli.mjs
min_file_count: 1
commit_message_pattern: "^docs\\(cli\\): document --verbose"
bash_syntax_check: []
forbidden_paths: []
must_contain:
- path: src/cli.mjs
pattern: "emit per-step trace"
```
## Verification
Final acceptance run after step 7:
```bash
node --test tests/ # all 26 tests pass (24 + 2 new)
node src/cli.mjs login alice > /tmp/out 2>/dev/null
diff /tmp/out tests/golden/login.stdout # exit 0
node src/cli.mjs login --verbose alice 2>/tmp/err 1>/dev/null
grep -c "\[verbose\]" /tmp/err # ≥ 3
node src/cli.mjs --help | grep -c "\-v, --verbose" # 1
```
## Plan-critic notes
- No deferred decisions: every step names its files, lines, and exact
string changes.
- TDD: stability harness (step 2) precedes behavior changes (steps 3-5).
- Verify commands are runnable, not "test it works".
- Steps 5 wires 5 files in one commit; this is over the 1–2 file
guideline but is justified by symmetry — the change is mechanical
and atomic across the five files; splitting would create five tiny
commits with no test value between them.
## Execution Strategy
Single session, 7 steps, ~15-20 minutes. No parallel decomposition needed.

112
plugins/ultraplan-local/examples/01-add-verbose-flag/progress.json Normal file
View file

@ -0,0 +1,112 @@
{
"schema_version": "1",
"slug": "add-verbose-flag",
"plan": ".claude/projects/2026-05-01-add-verbose-flag/plan.md",
"plan_path": ".claude/projects/2026-05-01-add-verbose-flag/plan.md",
"plan_version": "1.7",
"mode": "single",
"session_start_sha": "ab1c2d3e4f5g6h7i8j9k0l1m2n3o4p5q6r7s8t9",
"started_at": "2026-05-01T10:14:32Z",
"updated_at": "2026-05-01T10:31:08Z",
"status": "completed",
"current_step": 7,
"total_steps": 7,
"steps": [
{
"n": 1,
"title": "Capture golden stdout for stability test",
"status": "completed",
"started_at": "2026-05-01T10:14:32Z",
"completed_at": "2026-05-01T10:16:01Z",
"commit_sha": "c1d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0",
"files_changed": [
"tests/golden/login.stdout",
"tests/golden/whoami.stdout",
"tests/golden/users-list.stdout"
],
"verify_passed": true
},
{
"n": 2,
"title": "Add stability test (must FAIL initially — verbose not yet wired)",
"status": "completed",
"started_at": "2026-05-01T10:16:01Z",
"completed_at": "2026-05-01T10:18:42Z",
"commit_sha": "d2e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1",
"files_changed": [
"tests/cli-no-verbose-stability.test.mjs"
],
"verify_passed": true
},
{
"n": 3,
"title": "Extend parser to recognize --verbose and -v",
"status": "completed",
"started_at": "2026-05-01T10:18:42Z",
"completed_at": "2026-05-01T10:20:55Z",
"commit_sha": "e3f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2",
"files_changed": [
"src/cli.mjs"
],
"verify_passed": true
},
{
"n": 4,
"title": "Pass verbose into handler ctx",
"status": "completed",
"started_at": "2026-05-01T10:20:55Z",
"completed_at": "2026-05-01T10:22:13Z",
"commit_sha": "f4a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3",
"files_changed": [
"src/cli.mjs"
],
"verify_passed": true
},
{
"n": 5,
"title": "Wire verbose output in login, token-refresh, users-list, users-create, logout",
"status": "completed",
"started_at": "2026-05-01T10:22:13Z",
"completed_at": "2026-05-01T10:27:34Z",
"commit_sha": "a5b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4",
"files_changed": [
"src/commands/login.mjs",
"src/commands/token-refresh.mjs",
"src/commands/users-list.mjs",
"src/commands/users-create.mjs",
"src/commands/logout.mjs"
],
"verify_passed": true
},
{
"n": 6,
"title": "Add verbose-content test for login",
"status": "completed",
"started_at": "2026-05-01T10:27:34Z",
"completed_at": "2026-05-01T10:29:51Z",
"commit_sha": "b6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5",
"files_changed": [
"tests/cli-verbose-flag.test.mjs"
],
"verify_passed": true
},
{
"n": 7,
"title": "Update --help text",
"status": "completed",
"started_at": "2026-05-01T10:29:51Z",
"completed_at": "2026-05-01T10:31:08Z",
"commit_sha": "c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
"files_changed": [
"src/cli.mjs"
],
"verify_passed": true
}
],
"stats": {
"total_duration_ms": 996000,
"verify_failures": 0,
"manifest_failures": 0,
"rollbacks": 0
}
}

87
plugins/ultraplan-local/examples/01-add-verbose-flag/research/01-cli-parser-conventions.md Normal file
View file

@ -0,0 +1,87 @@
---
type: ultraresearch-brief
research_version: 1.0
question: How does small-auth currently parse arguments and where should --verbose hook in?
confidence: 0.85
dimensions: 4
created: 2026-05-01
---
# CLI parser conventions in small-auth
## Executive Summary
`small-auth` uses a hand-rolled argv parser at `src/cli.mjs:12-58` with a
two-pass approach: first pass extracts global flags (currently
`--help`, `--version`), second pass dispatches to command handlers in
`src/commands/*.mjs`. Adding `--verbose` requires touching only the
first-pass extractor and a new `verbose` parameter in the handler
contract — six command handlers each get a one-line update.
The parser does **not** use `commander`, `yargs`, or any external
library — this is intentional (zero deps) and consistent with the
plugin marketplace's broader convention. We keep that.
`stderr` is currently unused except for fatal errors. Adding verbose
output to stderr does not collide with anything.
Confidence: 0.85. The 0.15 uncertainty is around whether
`--verbose` should propagate into nested helper modules
(`src/lib/auth-token.mjs` calls `src/lib/db.mjs`); the plan should
either pass `verbose` via a context object or use a module-scoped
log function. Both work; the brief doesn't specify, so the planner
will choose.
## Dimensions
### 1. Argument-parsing layer
The parser at `src/cli.mjs:12-58` returns
`{globalFlags: {help, version}, command, positional, commandFlags}`.
We add `verbose: boolean` to `globalFlags`. The two-pass design means
`--verbose` works in any position automatically — no extra effort.
`-v` short form maps to `--verbose` via the existing alias table at
`src/cli.mjs:34`.
### 2. Command-handler contract
Each handler in `src/commands/*.mjs` exports
`async function run(positional, flags, ctx)`. Today `ctx` is
`{stdout, stderr, env}`. We extend `ctx` with `verbose: boolean` so
handlers can branch on it without re-reading globalFlags.
### 3. Internal log emission pattern
Existing fatal errors call `ctx.stderr.write(\`[error] ...\\n\`)`. The
verbose pattern matches: `if (ctx.verbose) ctx.stderr.write(\`[verbose] ...\\n\`)`.
No log helper needed for this iteration — six call sites total. Refactoring
into a `verbose()` helper is reasonable but not required for the goal.
### 4. Test infrastructure
Tests live in `tests/*.test.mjs` using `node:test`. Existing tests run
the CLI as a subprocess via `child_process.execFile` and assert on
exit code + stdout. Two new tests are needed:
- `tests/cli-verbose-flag.test.mjs` — assert `login --verbose alice`
exits 0, stderr contains "[verbose]", stdout matches golden file.
- `tests/cli-no-verbose-stability.test.mjs` — assert
`login alice` stdout is byte-identical to `tests/golden/login.stdout`.
## Citations
- `src/cli.mjs:12-58` — parser implementation
- `src/commands/login.mjs:8-42` — typical handler shape
- `tests/cli-help.test.mjs:14` — subprocess testing pattern
- `package.json:scripts.test` — `node --test tests/*.test.mjs`
## Brief anchoring
Brief task: "Add a --verbose flag to the small-auth CLI parser".
This research answers the planner's first question: where to hook
into. The parser is small and centralized, so the change is
minimal-scope.
The brief's success criteria around byte-identical default stdout
maps directly to the stability test in dimension 4.

73
plugins/ultraplan-local/examples/README.md Normal file
View file

@ -0,0 +1,73 @@
# Examples
Complete kalibrerte walk-throughs of the ultraplan-local pipeline for
realistic tasks. Each example shows the four artifacts a project
directory contains after a full run:
- `brief.md` — task brief from `/ultrabrief-local`
- `research/*.md` — research briefs from `/ultraresearch-local`
- `plan.md` — implementation plan from `/ultraplan-local`
- `progress.json` — execution log from `/ultraexecute-local`
These are **hand-calibrated**, not LLM-generated. The point is to give
a fork-er a deterministic reference — what the artifacts look like
when everything goes right, with a small but real task.
## Running pipeline yourself
For your own work, point the four commands at a real project directory:
```bash
mkdir -p .claude/projects/2026-05-01-my-task
/ultrabrief-local
/ultraresearch-local --project .claude/projects/2026-05-01-my-task
/ultraplan-local --project .claude/projects/2026-05-01-my-task
/ultraexecute-local --project .claude/projects/2026-05-01-my-task
```
The artifacts in each example mirror that flow.
## Examples
### 01-add-verbose-flag
**Task:** add a `--verbose` flag to a small CLI parser. Touches one
parser file and six command handlers; adds two tests.
**Why this example:** small enough to read end-to-end in 10 minutes,
but exercises every artifact (research with brief-anchoring, plan with
manifests, progress.json with multi-step git history). Demonstrates
how `plan_version: 1.7` schema looks in real life — including the
manifest YAML block per step and the `must_contain` list-of-dicts
form.
**What to study first:**
1. `brief.md` — note the explicit `Out of scope` section and concrete
`Success Criteria` (no "make it work" hand-waving).
2. `plan.md` Step 1 — note that the FIRST step captures golden output
*before* any behavior change. This is the stability harness pattern.
3. `plan.md` Step 5 — note that this step touches 5 files in one
commit, and the plan justifies the deviation from the 1–2 file
guideline. Plan-critic should accept that justification.
4. `progress.json` — every step has both `commit_sha` and
`verify_passed`. Resumes work from the last completed step.
## Regeneration
Each example has a `REGENERATED.md` documenting the version it was
calibrated against. When the artifact format changes, the example
needs to be re-built. See the `REGENERATED.md` file in each example
for triggers and procedure.
## Adding a new example
If you have a small, realistic task (touches 1-3 files, has a clear
success criterion, finishes in under 30 minutes) and want to add it
as an example:
1. Create `examples/NN-slug-here/` with the same four artifacts.
2. Add a `REGENERATED.md` documenting the calibration date and version.
3. Add a section to this README under `## Examples`.
4. Open an issue on the marketplace describing what the example
teaches that 01 doesn't already teach.