diff --git a/README.md b/README.md index eb8b448..63aa276 100644 --- a/README.md +++ b/README.md @@ -61,20 +61,23 @@ Key commands: `/config-audit posture`, `/config-audit feature-gap`, `/config-aud --- -### [Ultra {brief | research | architect | plan | execute} - local](plugins/ultraplan-local/) `v2.2.0` +### [Ultra {brief | research | architect | plan | execute} - local](plugins/ultraplan-local/) `v2.3.0` -Deep requirements gathering, research, Claude Code feature matching, implementation planning, and self-verifying execution with specialized agent swarms, adversarial review, and failure recovery. +Deep requirements gathering, research, Claude Code feature matching, implementation planning, self-verifying execution, and skill-factory authoring with specialized agent swarms, adversarial review, IP-hygiene scoring, and failure recovery. -Five commands, one pipeline with clear division of labor: +Five core commands plus an authoring command, one pipeline with clear division of labor: - **`/ultrabrief-local`** — Capture intent. Dynamic, quality-gated interview: a section-driven completeness loop (Phase 3) followed by a `brief-reviewer` stop-gate (Phase 4, max 3 review iterations). Required sections must reach an initial-signal gate AND pass review across completeness, consistency, testability, scope clarity, and research-plan validity before `brief.md` is written. Identifies research topics with copy-paste-ready `/ultraresearch-local` commands. Optional auto-orchestration runs research + planning in foreground. Always interactive. - **`/ultraresearch-local`** — Gather context. Deep multi-source research with triangulation: 5 local agents + 4 external agents + Gemini bridge, producing structured briefs with confidence ratings. Makes no build decisions. - **`/ultra-cc-architect-local`** *(optional, v2.2)* — Match Claude Code features to the task. Reads `brief.md` + `research/*.md`, consults a seeded CC-feature catalog skill (hooks, subagents, skills, output styles, MCP, plan mode, worktrees, background agents), and produces `architecture/overview.md` with brief-anchored rationale plus `architecture/gaps.md` with issue-ready drafts for missing catalog entries. Hallucination gate (enforced by `architecture-critic`) blocks proposals for features not covered by the catalog. - **`/ultraplan-local`** — Transform intent into an executable contract. Per-step YAML manifests (`expected_paths`, `commit_message_pattern`, `bash_syntax_check`). Plan-critic is a hard gate on manifest quality. Requires a task brief as input (`--brief` or `--project`). Auto-discovers the architecture note when present and cross-references its `cc_features_proposed` against exploration findings. - **`/ultraexecute-local`** — Execute the contract disciplined. Manifest-based verification, independent Phase 7.5 audit from git log + filesystem (ignores agent bookkeeping), Phase 7.6 bounded recovery dispatch for missing steps. Step 0 pre-flight catches sandbox push-denial before any work. `--validate` mode offers a fast schema-only sanity-check between planning and execution. +- **`/ultra-skill-author-local`** *(authoring, v2.3, skill-factory Fase 1)* — Generate one `cc-architect-catalog` draft skill from a curated local source file with IP-hygiene enforcement. Sequential pipeline: `concept-extractor` → `skill-drafter` → `ip-hygiene-checker`. Drafts land in `skills/cc-architect-catalog/.drafts/` for manual review and `mv` promotion. Pure-Node n-gram containment scorer (`scripts/ngram-overlap.mjs`) enforces verdict bands; rejected drafts are deleted. Channel 2 of the skill-factory strategy — manual, one-source-at-a-time, no automation. All artifacts land in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `architecture/` *(v2.2)*, `plan.md`, `sessions/`, and `progress.json`. `--project ` works across `/ultraresearch-local`, `/ultra-cc-architect-local`, `/ultraplan-local`, and `/ultraexecute-local`. +v2.3 (non-breaking) ships the skill-factory Fase 1 MVP: `/ultra-skill-author-local` plus four supporting agents (1 opus orchestrator + 3 sonnet workers) and `scripts/ngram-overlap.mjs` (pure Node stdlib, word-5-gram containment + longest-run secondary signal, calibrated against three source/draft fixture pairs). Catalog growth is now tractable without touching the architect's hallucination gate. Non-goals stay explicit: no automation, no batch, no decision-layer skills, no remote sources — manual `mv` from `.drafts/` to catalog root is the promotion mechanism. + v2.2 (non-breaking) adds the optional `/ultra-cc-architect-local` step between research and planning. The architect phase is backed by a versioned catalog skill (`cc-architect-catalog`) with 10 seed entries across three layers (reference, pattern, decision). Gaps are captured as issue-ready drafts so the catalog grows from real usage rather than speculation. `/ultraplan-local` auto-discovers the architecture note — existing pipelines keep working unchanged. v2.1 (non-breaking) replaced the hardcoded Q1–Q8 interview with a dynamic, quality-gated loop; `brief-reviewer` emits machine-readable per-dimension JSON scores so `/ultrabrief-local` can use it as an internal stop-gate. v2.0 (breaking) extracted the interview from planning: briefs are reviewable artifacts that downstream agents (`brief-reviewer`, `plan-critic`, `scope-guardian`) validate independently. `/ultraplan-local` requires `--brief` or `--project`. See `plugins/ultraplan-local/MIGRATION.md`. diff --git a/plugins/ultraplan-local/CHANGELOG.md b/plugins/ultraplan-local/CHANGELOG.md index a57ba12..f573ae3 100644 --- a/plugins/ultraplan-local/CHANGELOG.md +++ b/plugins/ultraplan-local/CHANGELOG.md @@ -4,6 +4,71 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). +## [2.3.0] - 2026-04-18 + +### Added — Skill-factory Fase 1 MVP (`/ultra-skill-author-local`) + +Manual one-skill-at-a-time generator for the `cc-architect-catalog`. +Channel 2 of the skill-factory strategy: a curated local source enters, +one draft skill exits in `skills/cc-architect-catalog/.drafts/`, with +n-gram containment scored against the source and stamped into the +draft frontmatter (or the draft is deleted when overlap is too high). + +**Why now.** `/ultra-cc-architect-local` (v2.2.0) enforces a +hallucination gate that only permits feature proposals backed by the +catalog. With 10 seed skills covering 8 features × 2 layers, the +`feature-matcher` rarely finds a match and silently produces empty +proposals. Fase 1 unblocks catalog growth without spinning up +automation: one source, one draft, manual review, manual `mv` for +promotion. + +**Pipeline.** Sequential, no retry, no parallelism: + +``` +/ultra-skill-author-local + → concept-extractor (sonnet, JSON output, gap-class C/D + cc_feature gate) + → skill-drafter (sonnet, .drafts/.md with 9-field frontmatter) + → ip-hygiene-checker (sonnet, runs scripts/ngram-overlap.mjs) + verdict accepted/needs-review → stamp ngram_overlap_score + verdict rejected → rm draft (no preservation) +``` + +**IP-hygiene utility.** Pure Node stdlib. Word-5-gram containment +similarity (asymmetric draft⊆source) plus longest-consecutive-shingle- +run secondary signal. Verdict bands: accepted (<0.15 AND <8), +needs-review (mid), rejected (≥0.35 OR ≥15). Short-text fallback to +n=4 when min(words) <500. CLI emits JSON. + +**Calibration fixtures.** Three source/draft pairs in +`tests/fixtures/skill-factory/` pin the verdict bands against +representative prose: accepted (containment 0.014), needs-review +(0.211), rejected (0.676). Re-verify any threshold change against +these fixtures. + +**New files:** + +- `commands/ultra-skill-author-local.md` +- `agents/skill-author-orchestrator.md` (opus) +- `agents/concept-extractor.md` (sonnet) +- `agents/skill-drafter.md` (sonnet) +- `agents/ip-hygiene-checker.md` (sonnet) +- `scripts/ngram-overlap.mjs` + `scripts/ngram-overlap.test.mjs` +- `skills/cc-architect-catalog/.drafts/.gitkeep` +- `tests/fixtures/skill-factory/{source,draft}-{accepted,needs-review,rejected}.md` +- `tests/fixtures/skill-factory/README.md` + +**Non-goals (explicit, Fase 1):** + +- No automation, cron, or watcher +- No CC changelog diffing or auto-research +- No batch processing or review command +- No decision-layer skills (cross-feature comparison is Fase 2+) +- No URL or remote sources — local files only +- Manual `mv` from `.drafts/` to catalog root is the promotion mechanism + +**New stats file:** +`${CLAUDE_PLUGIN_DATA}/ultra-skill-author-local-stats.jsonl`. + ## [2.2.0] - 2026-04-18 ### Added — `/ultra-cc-architect-local` optional pipeline step diff --git a/plugins/ultraplan-local/README.md b/plugins/ultraplan-local/README.md index 1e0dbef..b93f905 100644 --- a/plugins/ultraplan-local/README.md +++ b/plugins/ultraplan-local/README.md @@ -13,6 +13,7 @@ A [Claude Code](https://docs.anthropic.com/en/docs/claude-code) plugin for deep | **`/ultra-cc-architect-local`** | Architect (optional) — match brief+research against available CC features; produce architecture note with explicit gaps | | **`/ultraplan-local`** | Plan — agent swarm exploration, Opus planning, adversarial review | | **`/ultraexecute-local`** | Execute — disciplined step-by-step implementation with failure recovery | +| **`/ultra-skill-author-local`** | Authoring (v2.3, skill-factory Fase 1) — generate one cc-architect-catalog draft from a local source with IP-hygiene | Every artifact lives in one project directory: `.claude/projects/{YYYY-MM-DD}-{slug}/` contains `brief.md`, `research/NN-*.md`, `architecture/overview.md` (+ `gaps.md`), `plan.md`, `sessions/`, and `progress.json`. @@ -395,6 +396,52 @@ The executor implements defense-in-depth security across four layers: --- +## `/ultra-skill-author-local` — Authoring *(skill-factory Fase 1, v2.3)* + +Manual one-skill-at-a-time generator for the `cc-architect-catalog`. Channel 2 of the skill-factory strategy: a curated local source enters, one draft skill exits in `skills/cc-architect-catalog/.drafts/` with its n-gram containment score against the source stamped into the frontmatter (or the draft is deleted when the overlap is too high). + +### Why it exists + +`/ultra-cc-architect-local` enforces a hallucination gate that only permits feature proposals backed by the catalog. With 10 seed skills covering 8 features × 2 layers, the matcher rarely finds support and silently produces empty proposals. This command grows the catalog without spinning up automation: one source → one draft → manual review → manual `mv` for promotion. + +### Pipeline + +Sequential, no retry, no parallelism: + +``` +/ultra-skill-author-local + → concept-extractor (sonnet) → JSON: cc_feature, layer, slug + → skill-drafter (sonnet) → .drafts/.md, 9-field frontmatter + → ip-hygiene-checker (sonnet) → runs scripts/ngram-overlap.mjs + verdict accepted/needs-review → stamp ngram_overlap_score + verdict rejected → rm draft (no preservation) +``` + +### Modes + +| Mode | Usage | Behavior | +|------|-------|----------| +| **Default** | `/ultra-skill-author-local ` | Run the pipeline (concept → draft → IP-hygiene) foreground | +| **`--fg`** | `/ultra-skill-author-local --fg` | Same as default; flag accepted for pipeline-convention consistency | +| **`--quick`** | `/ultra-skill-author-local --quick` | Skip IP-hygiene with BIG WARNING (drafting-pipeline test only) | + +### IP-hygiene utility + +`scripts/ngram-overlap.mjs` — pure Node stdlib, zero dependencies. Word-5-gram containment similarity (asymmetric draft⊆source) plus longest-consecutive-shingle-run secondary signal. Verdict bands: `accepted` (<0.15 AND <8), `needs-review` (mid), `rejected` (≥0.35 OR ≥15). Short-text fallback to n=4 when min(words) <500. CLI emits JSON. + +Calibration fixtures in `tests/fixtures/skill-factory/` pin the verdict bands against representative prose. Re-verify any threshold change against these fixtures. + +### Non-goals (explicit, Fase 1) + +- No automation, cron, or watcher +- No CC changelog diffing or auto-research +- No batch processing or review command +- No decision-layer skills (cross-feature comparison is Fase 2+) +- No URL or remote sources — local files only +- Manual `mv` from `.drafts/` to catalog root is the promotion mechanism + +--- + ## The full pipeline ```