add /ctx-task-out — close the spec→implement gap in the canonical chain#129
Merged
Conversation
First real consumption of the 5-step chain (zhc/os m0a) showed the operator reverse-engineering the pipeline's mental model from skill texts: /ctx-plan is absent from design-before-coding.md's TL;DR, and nothing documents brief-per-bet vs plan-per-milestone altitude, the rolling-wave and blocking-TBD gates from the operator's seat, the ledger/projection two-surface rule, or when a new brief is warranted. Seven-point recipe task added to Misc (priority high). Follow-up surfaced by the ctx-task-out work order's first consumer; documenting the chain it completed inherits its spec. Spec: specs/ctx-task-out.md Signed-off-by: Jose Alekhinne <jose@ctx.ist>
The machine-readiness question ("can this box build, lint, site-render,
and reach the MCP servers?") had no single answer; gaps surfaced
mid-task instead of up front — a doc-link session discovered zensical
and pipx missing only after the source edits were done, and this very
machine could not run make lint until today. One manifest
(hack/tool-versions.txt) pins minimums; one script probes PATH
binaries, npm drift, and claude-registered MCP servers and prints one
verdict table. Required failures (go, git, golangci-lint) exit
non-zero; optional ones warn; probes degrade to SKIP without network
or the claude CLI, never hang.
Spec: specs/check-tools.md
Signed-off-by: Jose Alekhinne <jose@ctx.ist>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A reported 404 on recipes/activating-context/ turned out to be one of four breakage classes: two nav entries pointing at recipes deleted by the cwd-anchored change, six absolute ctx.ist URLs stranded by old restructures (README's manifesto/cli-reference/context-files/ integrations links, a blog autonomous-loop link, configuration.md's self-reference), ten intra-doc anchors orphaned when commands were re-homed to their own CLI pages, and a /ctx-prompt row surviving the prompt-template removal. Every replacement URL was verified live before the edit; zensical's build-time anchor checker now reports zero issues. Spec: specs/docs-link-integrity.md Signed-off-by: Jose Alekhinne <jose@ctx.ist> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Prose shipped from AI-assisted sessions carries recognizable tells (significance inflation, brochure language, forced triplets, em-dash density, chatbot residue) and readers increasingly discount text that pattern-matches to machine output; hack/detect-ai-typography.sh flags the typography but nothing fixed the writing. The skill splits a 1,024-line first draft into a ~200-line rule sheet (invariants, modes, protected content, cluster-based detection) and an on-demand 28-pattern before/after catalog under references/. Guardrails a live test shaped: voice additions must trace to the author's material, filler deletion is not coverage loss, removing fake attribution must not silently strengthen a claim, and the em-dash ban is verified by grep rather than eyeball. Spec: specs/ctx-humanize.md Signed-off-by: Jose Alekhinne <jose@ctx.ist> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
A session's cost and context pressure were invisible while it runs; ctx usage reports tokens only after the fact. ctx system statusline renders the statusLine stdin payload as one sanitized line (user@host dir | model | ctx: N% | $C.CC) and ctx init wires it into settings.local.json, backing up any pre-existing statusLine to .context/state/ and restoring it on statusline.enabled: false. The line is deliberately informational: no spend alarms and no model-switch nudges, because a family-substring rule has no task context and cost-per-turn is the wrong unit (the spec's Decisions section records the full rationale). Also fixes a latent data-loss bug this feature would have tripped: the permissions merge round-tripped settings.local.json through a typed struct, silently dropping every key ctx does not model (env, statusLine, ...) on re-init. Both merges now do raw-map surgery so unmodeled keys survive byte-for-byte. Includes the rebuilt site/ for this session's docs changes. Spec: specs/statusline.md Signed-off-by: Jose Alekhinne <jose@ctx.ist> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This repository is public but is developed alongside internal tooling, and tracked files had accumulated identifiers that do not belong in a public tree: internal hostnames and a mirror-repo name in two archived specs and DECISIONS.md, and internal-lineage notes in a task entry, a spec cross-reference, and the experimental-skill headers. Redactions preserve each sentence's meaning and every structure invariant (tasks edited in place, decisions keep their rationale); designs stay described on their own merits, without attribution. TASKS.md also carries this session's ledger entries (check-tools, ctx-humanize, delta analysis, statusline: all closed). Spec: specs/public-repo-hygiene.md Signed-off-by: Jose Alekhinne <jose@ctx.ist> Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The deployed CLAUDE.md and Copilot INSTRUCTIONS treated a missing ctx
binary as fatal ("CRITICAL, not optional": relay, STOP), which
punishes exactly the contributor the templates first meet: someone
who cloned a ctx-using project without installing ctx got an agent
that refused ordinary work. Both templates now distinguish not-found
(mention the setup once, then proceed with the task; the Claude
variant recommends installing the plugin from a local clone since
marketplace releases lag the repository) from installed-but-erroring
(unchanged: relay verbatim, STOP, recovery is the user's decision).
Spec: specs/optional-ctx-onboarding.md
Signed-off-by: Jose Alekhinne <jose@ctx.ist>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The design-to-implementation chain had an unowned artifact:
/ctx-plandisclaims implementation planning,
/ctx-speccommits the what/why atspec altitude, and
/ctx-implementopens with "use when you have aplan document" — which nothing in the chain produced. This PR adds the
missing fourth step:
/ctx-task-outdecomposes a committed spec into a per-milestone planat
specs/plans/<milestone>.md— data model, contracts, invariant testmatrix, and commit-sized tasks with falsifiable acceptance criteria.
Its signature move matches the rest of the chain: it refuses to run
ahead of its inputs (blocking-TBD gate, rolling-wave gate, milestone
boundaries owned by the spec) rather than degrading. The plan is the
execution ledger; TASKS.md carries epic-level anchors only.
Also included: a fix for Claude 5 family context-window detection —
claude-fable-5sessions fell to the 200k default and thecheck-context-size hook warned "104% full" on a 79%-free 1M session.
Commits
7c1eb0e3— add /ctx-task-out (Spec: specs/ctx-task-out.md)hack/sync-copilot-skills.sh), registered in the permissionsallowlist and
ctx initworkflow tips/ctx-spec: tasking handoff in interactive and--briefflows/ctx-implement: namesspecs/plans/<milestone>.mdas canonicalinput, redirects bare multi-milestone specs, refuses
Status: Blockedplans, owns plan checkbox updatesspecs-READMElifecycle gains the task-out step/ctx-plansection and its dead anchor), common-workflows,integrations, three recipes
500c4a07— fix context window detection(
Spec: specs/model-context-window-fable.md)ModelContextWindowmaps the always-1M families:fable,mythos,sonnet-5(alongside existingopusand[1m])sonnet-4-6deliberately unchanged (Claude Code gates its 1Mbehind the
[1m]opt-in — see spec Non-Goals and DECISIONS.md)f37fd9fe— chore: refresh go.work.sum(
Spec: specs/meta/chores.md)Design notes for reviewers
The skill went through two external review rounds before landing.
Load-bearing pieces to scrutinize, in the order the work order's
Review section prescribes:
Status: Blockedreachable only via amendment (fresh runs refuseand write nothing)
invariants come from the spec (unstated invariant = spec gap, mark
TBD, never mint); TBD resolutions live in the spec or DECISIONS.md,
the plan only points at them
/ctx-implementupdates them, rolling-wave gate reads DoD onlyacceptance criteria never edited in place once a task starts
Verification
go vet,gofmt,lint-drift, style/version/why/copilot-sync checks,go test ./...zero failures (golangci-lint runs in CI; not installed locally)
gitnexus detect_changes: 66 symbols across 21 files, 0 affectedexecution flows, risk LOW
fable/mythos/sonnet-5→ 1M;sonnet-4-6→ 200k pinned)specs/v1-substrate.md(D-001 open → refusal fires by construction)Not in this PR / follow-ups
site/regeneration (make site) — generated output, rebuiltseparately
make build && sudo make install) so the live hookstops misreporting and the plugin picks up the skill
/ctx-task-outrun: zhc/osv1-substrate.mdm0a(expected: D-001 refusal; then the plan after D-001 resolves)
docs/reference/skills.mddrift sweep: 7 skills stillundocumented (
ctx-architecture-enrich,ctx-code-review,ctx-config,ctx-dream,ctx-explain,ctx-refactor,ctx-serendipity) plus a stalectx-promptrowallow.txt/write.yamlomit/ctx-planitself (pre-existing)