task-pipeline-skill 1.3.2 → 1.4.3

package/CHANGELOG.md

@@ -1,5 +1,64 @@
 # Changelog
 
+## v1.4.3 — 2026-07-30
+
+### Fixed
+- **`argument-hint` in the slash command was unquoted.** In YAML a bare
+  `[a | b]` is a flow sequence, not a string, so the hint parsed as a *list*.
+  Found by `claude plugin validate --strict`, the upstream schema checker, which
+  now runs in CI on both this plugin and its marketplace manifest.
+- **`homepage` and `repository` sat at the top level of `marketplace.json`,
+  where Claude Code does not recognize them.** They are plugin-entry fields;
+  moved there, so the values reach the plugin listing instead of being ignored.
+
+## v1.4.2 — 2026-07-30
+
+### Fixed
+- **`pipeline.schema.json` identified itself with a URL that 404s.** The `$id`
+  read `https://github.com/ssheleg/task-pipeline/pipeline.schema.json` — a path
+  that has never existed (no `blob/main`, wrong depth). This file is installed
+  into `~/.claude/skills/task-pipeline/`, so every install carried a schema
+  whose declared identity could not be fetched by anything resolving it. Now the
+  raw URL that actually serves the file, matching `agent-sync`'s convention.
+
+### Changed
+- `license: MIT` declared in the `marketplace.json` plugin entry and in the
+  skill's front matter — the `LICENSE` file was invisible to both surfaces.
+
+## v1.4.1 — 2026-07-30
+
+### Changed
+- `agent-sync` moved to **`ssheleg/agent-sync`**. The three places this skill
+  links to it — `SKILL.md`, `references/stages.md`, `references/acceptance.md` —
+  now point at the new owner rather than relying on GitHub's redirect.
+
+## v1.4.0 — 2026-07-29
+
+### `references/learned.md` — fourteen rules earned by failure, each with its incident
+
+Taught to the pipeline by a real build: a 229-decision specification across four repositories with
+several agents working at once. Every rule names the failure that produced it, because a rule with
+no incident behind it is somebody's preference and gets argued with at the worst moment.
+
+The ones that cost the most, now gate criteria rather than advice:
+
+- **A gate's exit code is part of its output.** One printed `FAIL` and returned `0`; CI had been
+  green over it for an unknown period.
+- **Doubt the probe first.** Five probes failed before any check did — four times out of five the
+  planted defect was never planted, and the silence read as a passing check.
+- **Absence needs its own check.** Comparing documents finds contradictions, and a contradiction
+  needs two sides; a whole missing subsystem has one. Only the reverse direction of a computed
+  mapping found it.
+- **Tests create what they assert on.** A test read another test file's leftovers, so it passed on a
+  warm database and failed on the cold one every new developer has.
+- **A generator seeds green** · **local infrastructure does not publish the host's default ports** ·
+  **compute rather than restate** · **sweep the class, not the finding** · **ratchet, never TODO**.
+
+Wired into stages 5, 6, 9 and 10 as gate criteria, not as reading. Two lessons are deliberately kept
+OUT of the table, as review questions — *is this the right citation* and *did this number come from
+the contract or from prose about it* — because a rule that pretends to be enforced and is not is the
+same failure as the gate that printed `FAIL` and exited `0`.
+
 ## v1.3.2 — 2026-07-29
 
 **The 26 negative self-tests could not be run anywhere except CI** — which meant

package/README.md

@@ -490,6 +490,19 @@ command into `~/.claude/commands/`; idempotent — rerun skips existing installs
 
 ### Updating
 
+**The family updates as one package** — a bundle with one member current and the rest stale is a
+combination nobody tested:
+
+```bash
+npx sshlg-skills update               # installed but behind — updates everything
+npx sshlg-skills install              # nothing installed yet
+npx --yes sshlg-skills@latest list    # what the current release of each member is
+```
+
+Restart your agent afterwards: skills and hooks load at session start.
+
+Per-channel, when you are updating this one member only:
+
 Pick **one** channel per agent — running the plugin and the plain/skills-CLI copy on
 the same Claude Code install yields a duplicate, shadowing skill.
 
@@ -551,13 +564,19 @@ Built by ssheleg — [sshlg.me](https://sshlg.me)
 - Telegram — [@sshlg](https://t.me/sshlg)
 
 Part of the [ssheleg skill family](https://github.com/ssheleg/sshlg-skills):
-`super-ux`, `task-pipeline`, `make-skill`, `sheleg-design`, `seo-aeo-audit`.
-One command installs all five for every agent you use:
+`super-ux`, `task-pipeline`, `agent-sync`, `make-skill`, `sheleg-design`, `seo-aeo-audit`.
+**The family installs and updates as one package**, for every agent you use — a bundle with one
+member current and the rest stale is a combination nobody tested:
 
 ```bash
-npx sshlg-skills install
+npx sshlg-skills install              # nothing installed yet — the whole family, any agent
+npx sshlg-skills update               # installed but behind — updates everything
+npx --yes sshlg-skills@latest list    # what the current release of each member is
 ```
 
+Restart your agent afterwards: skills and hooks load at session start, so the session that
+updates is not the session that gets the new ones.
+
 ## License
 
 MIT © 2026 ssheleg. Third-party portions (the ported stage doctrine) are credited

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "task-pipeline-skill",
-  "version": "1.3.2",
+  "version": "1.4.3",
   "description": "Full-cycle delivery pipeline for coding agents: a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine ships inside the skill — no companion plugin required. This package is the installer CLI.",
   "bin": {
     "task-pipeline": "bin/task-pipeline.js"

package/plugins/task-pipeline/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "task-pipeline",
   "description": "Runs a substantial task through a mandatory built-in intake grill, then 10 gated stages (docs, brainstorm+decompose, spec, plan, subagent build, tests, lint/deploy, post-deploy, docs/wiki, acceptance). Every stage's doctrine is built into the skill — no companion plugin required — with typed auto/manual gates, a frozen requirement spine that must close with evidence, a loop guard that breaks churn, one provider-agnostic model confirmed up front, and an optional super-ux UX track for user-facing work.",
-  "version": "1.3.2",
+  "version": "1.4.3",
   "author": {
     "name": "ssheleg"
   },

package/plugins/task-pipeline/commands/task-pipeline.md

@@ -1,6 +1,6 @@
 ---
 description: Run a task through task-pipeline — an intake grill that expands the request, then docs → brainstorm → spec → plan → build → tests → deploy → post-deploy → docs/wiki → acceptance.
-argument-hint: <one-line task description>
+argument-hint: "<one-line task description>"
 ---
 Use the `task-pipeline` skill to run the task below through all gated stages —
 **stage 0 intake grill** → docs study → brainstorm → spec → plan → subagent

package/plugins/task-pipeline/skills/task-pipeline/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: task-pipeline
 description: "Use when running a substantial task through the full end-to-end delivery pipeline — an up-front intake grill that expands the request into a complete brief, then docs study, brainstorm, spec, plan, subagent-driven build, tests, lint/deploy, post-deploy log check, docs/wiki sync and acceptance — as gated stages whose doctrine is built entirely into this skill (no required companion skills). Triggers - 'run this through the pipeline' / 'прогони по конвейеру', 'the full cycle' / 'полный цикл', /task-pipeline, or any substantial feature, fix, or build that should follow the disciplined cycle rather than ad-hoc coding. The intake grill is mandatory - it front-loads every decision, including the per-stage autonomy sweep, so stages 1→10 run without mid-flight questions; recommends super-ux for user-facing work; confirms one model up front (most capable available, never a hardcoded id); reads host-project conventions for deploy/docs/wiki so it stays project-agnostic."
+license: MIT
 ---
 
 # task-pipeline
@@ -189,12 +190,12 @@ capable available — see `references/model-tiering.md`).
 | 2 | Brainstorm + decompose | built in: [`references/brainstorm.md`](references/brainstorm.md) + **UI detection** + [`references/decomposition.md`](references/decomposition.md) for platforms | design approved; UI verdict recorded; every REQ answered; platform: module map approved | manual |
 | 3 | Spec | built in: [`references/spec.md`](references/spec.md) — **UI → super-ux chain first** (`/ux` → `ux-foundation` CJM → `ux-flows` screens → `ux-scenarios` → `/ux-lint`), then spec `docs/superpowers/specs/…-design.md` | committed + reviewed; UI: chain validated, linter green, scenarios/`SCR-` traced | manual |
 | 4 | Plan | built in: [`references/planning.md`](references/planning.md) → `docs/superpowers/plans/…md` | parallel-ready, DoD per task | auto |
-| 5 | Dev | built in: [`references/build.md`](references/build.md) (worktree → subagent per task → review loop → integrate) + [`references/tdd.md`](references/tdd.md) | tasks DONE, TDD green per task, branch integrated per the brief | auto |
-| 6 | Tests | host test runner + built-in [`references/tdd.md`](references/tdd.md) | full suite green; new/changed code covered | auto |
+| 5 | Dev | built in: [`references/build.md`](references/build.md) (worktree → subagent per task → review loop → integrate) + [`references/tdd.md`](references/tdd.md) | tasks DONE, TDD green per task, branch integrated per the brief; **anything generated passes its own checks, and local infrastructure does not publish the host's default ports** ([`references/learned.md`](references/learned.md)) | auto |
+| 6 | Tests | host test runner + built-in [`references/tdd.md`](references/tdd.md) + [`references/learned.md`](references/learned.md) | full suite green; new/changed code covered; **every new check probed both ways and asserted on its exit code**, and the suite run once against a cold environment | auto |
 | 7 | Lint + deploy | host lint → deploy per host convention | lint clean + suite green before deploy; deploy needs a go (or the brief's specific standing authorization) | manual |
 | 8 | Post-deploy | tail deploy logs / health-check | clean boot or honest degradation report | auto |
-| 9 | Docs + wiki | host module docs/runbook rules → `wiki-update` ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki), recommended) | every stale row of the stage-0 source ledger updated; docs synced; wiki synced | auto |
-| 10 | **Acceptance** | built in: [`references/audit.md`](references/audit.md) (ladder walk) → [`references/acceptance.md`](references/acceptance.md) (coverage table) | ladder walk ran, its absences became REQ rows; every REQ accounted for with evidence from a check seen failing once; ledger has no unresolved row; **in a multi-repository project, every repository is clean, pushed and pointed at** (below); operator signs off | manual |
+| 9 | Docs + wiki | host module docs/runbook rules → `wiki-update` ([obsidian-wiki](https://github.com/ar9av/obsidian-wiki), recommended) | every stale row of the stage-0 source ledger updated; docs synced; wiki synced; **every number computed rather than restated, every named command or file resolvable** ([`references/learned.md`](references/learned.md)) | auto |
+| 10 | **Acceptance** | built in: [`references/audit.md`](references/audit.md) (ladder walk) → [`references/acceptance.md`](references/acceptance.md) (coverage table) | ladder walk ran, its absences became REQ rows; every REQ accounted for with evidence from a check seen failing once; ledger has no unresolved row; **axis rotation recorded** (new findings vs self-inflicted, rule 1 of [`references/learned.md`](references/learned.md)), **every closure verified against the artefact rather than the document describing it**, **each correction swept across its class**, **every deferral a printed ratchet rather than a TODO**; **in a multi-repository project, every repository is clean, pushed and pointed at** (below); operator signs off | manual |
 
 
 ### Stage 10 in a project of several repositories
@@ -213,7 +214,7 @@ git -C <each repo> status --porcelain && git -C <each repo> log @{u}..HEAD --one
 ```
 
 report nothing — for the parent as well as every submodule. Where
-[agent-sync](https://github.com/appvillis-com/agent-sync) is installed, `/agent-sync finish` runs
+[agent-sync](https://github.com/ssheleg/agent-sync) is installed, `/agent-sync finish` runs
 exactly this plus *no lease left held*, and `--gates` adds the project's own gate commands.
 
 The fix, when it fails, is two commands and the second is the one that gets forgotten:
@@ -258,6 +259,7 @@ automation is on — `pipeline.schema.json` is the only contract.
 - `references/grill.md` — the built-in stage-0 grill: loop, domain awareness, autonomy sweep
 - `references/acceptance.md` — the built-in stage-10 close-out: REQ coverage, evidence, sign-off
 - `references/audit.md` — cross-cutting: the L0→L7 ladder and its seams (what was never written), axis rotation, ratchets, proven checks
+- `references/learned.md` — cross-cutting: fourteen rules earned by failure on a real multi-repository build, each with the incident behind it, its check and its exit criterion; plus the two that no check can decide
 - `references/brainstorm.md` — stage 2: design dialogue, approaches, UI detection, hard gate
 - `references/spec.md` — stage 3: UX track order, the spec contract, self-review, review gate
 - `references/planning.md` — stage 4: zero-context plan format, parallel groups, no placeholders

package/plugins/task-pipeline/skills/task-pipeline/pipeline.schema.json

@@ -1,6 +1,6 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://github.com/ssheleg/task-pipeline/pipeline.schema.json",
+  "$id": "https://raw.githubusercontent.com/ssheleg/task-pipeline/main/plugins/task-pipeline/skills/task-pipeline/pipeline.schema.json",
   "title": "task-pipeline config",
   "description": "Generic contract for a pipeline config. An ordered list of stages; each stage is run by the host project's own skills/agents and guarded by a typed gate. The framework imposes no specific stages, skills, or gate assignments — those are entirely the host project's config. Copy pipeline.example.json and rewrite it to match your project.",
   "type": "object",

package/plugins/task-pipeline/skills/task-pipeline/references/acceptance.md

@@ -124,7 +124,7 @@ git -C <each repo> status --porcelain
 git -C <each repo> log @{u}..HEAD --oneline
 ```
 
-Where [agent-sync](https://github.com/appvillis-com/agent-sync) is installed,
+Where [agent-sync](https://github.com/ssheleg/agent-sync) is installed,
 `/agent-sync finish` runs exactly this plus *no lease left held*, and `--gates`
 adds the project's own gate commands.
 

package/plugins/task-pipeline/skills/task-pipeline/references/learned.md

@@ -0,0 +1,135 @@
+# Rules earned by failure
+
+**One job: the mistakes that cost real time on a real project, each with the check that now catches
+it.** Every rule here names the incident that produced it. A rule with no incident behind it is
+somebody's preference, and it will be argued with at the worst moment.
+
+They come from one 229-decision, 72-document specification built across four repositories with
+several agents working at once. Nothing here is hypothetical.
+
+**A rule belongs in the table only when it has a check.** Two of the lessons below could not be
+mechanised and are kept out of it deliberately, as review questions — because a rule that pretends
+to be enforced and is not is the same failure as a gate that prints `FAIL` and exits `0`.
+
+---
+
+## The table — trigger · check · exit criterion
+
+| # | Rule | Trigger | The check | Exit criterion |
+|---|---|---|---|---|
+| 1 | **Change the axis when it stops paying** | any second review or audit pass | count new findings and self-inflicted ones separately | self-inflicted exceeds new → change the axis, do not "look again more carefully" |
+| 2 | **Absence needs its own check** | any two-layer model — entity/table, screen/frame, task/module, requirement/test | compute the mapping in **both** directions | zero orphans each way, printed |
+| 3 | **Verify closure against the artefact** | closing anything that names a design, a build or a file | open the artefact, not the document describing it | the artefact carries a marker naming what it was last verified against |
+| 4 | **Probe the detector** | every new check, lint rule or assertion | plant the defect → run → assert non-zero; restore → assert zero | both directions observed once, and recorded |
+| 5 | **Doubt the probe first** | a check that stays silent when it should fire | prove the planted defect exists in the text the check actually parses | the probe is shown to have changed what the check reads |
+| 6 | **Sweep the class, not the finding** | any correction | grep the whole corpus for the same shape before closing | the class is gated, or named in the note so the next reader can finish it |
+| 7 | **Ratchet, never TODO** | anything that cannot be fixed now | a named, counted set printed on every run | the number may only fall, and `OK` prints it beside itself |
+| 8 | **Compute, never restate** | any count or cross-reference stated in prose | derive it from the source at check time | the stated number and the computed one are the same object |
+| 9 | **A generator seeds green** | any scaffold, template or code generator | run the generated project's own checks inside the generator's tests | fresh output exits zero |
+| 10 | **Measure a detector before trusting it** | a new heuristic check | run it over the real corpus and count false positives | zero false positives, or the heuristic is replaced by a deterministic rule |
+| 11 | **A gate's exit code is part of its output** | any gate or CI step | run it against a planted defect and assert on `$?` | non-zero, not merely a `FAIL` line on stdout |
+| 12 | **Tests create what they assert on** | any test touching shared state | run the suite against a cold, empty environment | the cold run and the warm run agree |
+| 13 | **Local infrastructure does not fight the host** | any dev compose or service definition | assume the host already runs the defaults | services reachable with the host's own still running |
+| 14 | **A document may not send a reader to something absent** | any instruction naming a command, file or install | resolve it | the gate fails when the target does not exist |
+
+---
+
+## The incidents, so the rules are not abstract
+
+**1 · Change the axis.** Seven passes of comparing documents against each other were instrumented.
+Findings per pass: 12, 17, 13, 19 — and *caused by the previous pass*: 5, 9, 10, 4. By the sixth
+pass the method was mostly repairing itself, because each pass edits the corpus the next one reads,
+so the newest text is always the least reviewed. The fix is not more care; it is a different axis.
+
+**2 · Absence.** Comparing documents found contradictions for weeks and never found that one
+service had **no key store at all** — a decision made it the encryptor of every media object, the
+other service's table had been modelled for weeks, and this one had no entity, no fields, no
+rotation story. A contradiction needs two sides. Absence has one. The register that finally caught
+it checks *entity → table* and *table → entity*, and **only the second direction found anything**:
+four entities fully specified, cited by build tasks, with no schema anywhere.
+
+**3 · Closure against the artefact.** Two gaps were marked **closed** while the design still
+violated them — the closure had been verified by reading the specification, which had been fixed,
+while the frames had not. Twice is a category, so every drawn screen now carries a marker naming the
+newest decision its *frames* were checked against, and the linter fails when the prose cites
+something newer.
+
+**4 and 5 · Probes.** Every check written was exercised against a planted defect. **Five probes
+failed before any check did:** one added a definition where the check looks for an unresolved
+reference; one edited a string whose whitespace did not match; one hit the first prose mention
+instead of the table row; one flipped a row whose producer cell was empty, so nothing was planted;
+one counted matching lines and counted the check's own `INFO` line as a hit. Four times out of five
+the probe was wrong, not the check.
+
+**6 · Sweep the class.** A pass fixed four invented audit-action names in a table and stopped at the
+rows it was looking at; two rows in the same table still said something else, found the next day.
+The same shape recurred three times — a retired word corrected on one screen and left on two others,
+a value fixed in a light frame and left in its dark twin, a stale retention window removed from
+three documents' prose and surviving in a design.
+
+**8 · Compute.** Two documents had to stop quoting totals after they went stale. The register that
+replaced them computes its cross-reference column from lines the tables themselves carry, so the two
+cannot disagree.
+
+**9 · Seeds green.** A documentation gate added to a scaffold **failed on its own seeds** — it read
+the template block and the allocation line as real identifiers. A project that starts red teaches
+everyone on day one that the gate is noise.
+
+**10 · Measure the detector.** A parity-based check for unbalanced markup produced **six false
+positives out of six** on the real corpus. It was discarded for a deterministic rule. A gate that
+cries wolf is removed by the third person who hits it.
+
+**11 · Exit codes.** A repository's docs gate appended a check *after* its verdict block, so it
+printed `FAIL` and returned `0`. CI had been green over it for an unknown period.
+
+**12 · Cold runs.** An isolation test read whatever another test file had left in the database. Test
+files run alphabetically and the one that creates that data runs later, so the test **passed on a
+warm database and failed on a cold one** — which is what every new developer has.
+
+**13 · Ports.** A dev compose published the default Postgres and Redis ports. The machine already
+ran both, so the containers were silently shadowed: the tools connected to the host's services and
+the migration failed with a permission error that named nothing about the collision.
+
+**14 · Absent targets.** A repository's first instruction to every agent was to run a command that
+was not installed, with no install line anywhere and no statement of what a session without it
+actually is.
+
+---
+
+## The two that are not in the table, and why
+
+Kept as review questions, because no check can decide them:
+
+- **Is this the right citation?** A stale reference was replaced with a *false* one — the new target
+  existed and said nothing about the subject. A gate can prove an identifier resolves; only a reader
+  can prove it is the right one. **Ask at review: did you open the target and confirm it says the
+  thing?**
+- **Does the prose match the contract, or another paragraph of prose?** A "correction" to an attempt
+  cap introduced a second vocabulary for one counter, because it was written against a description
+  instead of the schema. **Ask at review: which artefact did this number come from?**
+
+---
+
+## The one instruction that would have prevented the most
+
+> **Before trusting any tool's report about the world, make it report something you can already
+> verify.**
+
+Four of the worst failures on that project were the same failure wearing different clothes: a test
+suite reporting green having skipped every assertion; a gate printing `FAIL` and exiting `0`;
+containers reporting healthy while the tools talked to the host's services; a coordination plugin
+reporting a lease held by an identity that belonged to a different session. In each case the tool
+was describing a world it was not looking at, and in each case one deliberate check against a known
+answer would have exposed it in a minute.
+
+---
+
+## Where these bind in the pipeline
+
+| Stage | Rules that apply |
+|---|---|
+| 3 Spec · 4 Plan | 2 (both directions), 8 (compute, never restate) |
+| 5 Dev | 9 (generators seed green), 12 (tests create their own state), 13 (local infra) |
+| 6 Tests | 4, 5, 10, 11 — every new check probed both ways, measured, and asserted on its exit code |
+| 9 Docs | 8, 14 — every number computed, every target resolvable |
+| 10 Acceptance | 1, 3, 6, 7 — axis rotation recorded, closure verified against artefacts, classes swept, ratchets printed |

package/plugins/task-pipeline/skills/task-pipeline/references/stages.md

@@ -309,7 +309,7 @@ stages/agents/types (see SKILL.md → *Bring your own skills*).
   reports nothing **for the parent as well as every submodule**:
   `git submodule status` (no line starting `+`), plus `git -C <repo> status
   --porcelain` and `git -C <repo> log @{u}..HEAD --oneline` per repo. With
-  [agent-sync](https://github.com/appvillis-com/agent-sync) installed,
+  [agent-sync](https://github.com/ssheleg/agent-sync) installed,
   `/agent-sync finish` runs exactly that. The fix is two commands and the second is
   the forgotten one: `git -C <submodule> push`, then
   `git add <submodule> && git commit`.