ot-spec

Installation
SKILL.md
  1. Read on-track/tracks/NNN-slug/intent.md in the target repo. Intent status may stay draft. Classify each unanswered item under Open questions:
    • Blocking questions: an answer changes scope, security, data persistence, external integration, architecture, or acceptance. Resolve every one before the summary, on the Highway and in Off Road alike. When the user answers "you decide", decide, record the decision in spec.md under Constraints, marked (delegated), and list it in the summary for veto. Withhold the summary and do not offer . para implementar while any blocking question remains unanswered.
    • Deferrable questions: questions whose answers do not block overall architecture or scope. Turn each deferrable question into a bounded task whose Validate names the expected answer or artifact, placed in a group that dependent groups list in (depends: ...). Without delegation, do not invent answers to either kind. How to ask:
    • Settled: before asking, check whether the point is already settled. A point is settled when one of these answers it: the intent, the context you already hold (AGENTS.md, files read this session), a lookup tool the project names for this (code graph, memory), or one targeted read (a manifest, .env.example, on-track/decisions/). Use the settled answer and cite its source where the spec relies on it. Ask only what is still open after that check.
    • Suggestion: a recorded decision (an ADR, a documented choice) stays as written. A choice that is only in use, with no recorded reason, may receive a suggestion when a clearly better option serves the request, such as a more established library that fits the project. Put it in the round with your recommendation first, as one of its questions.
    • Serve the request as stated: each question clarifies what the intent asks or proposes a way to reach it, within its outcome and out-of-scope limits.
    • Round: at most four questions, through the host's question tool when it exists, all on one theme (data model, then libraries, then infrastructure); close a theme before opening the next. Each question names the decision it unlocks and offers options with your recommendation first.
    • Highway: ask in rounds of at most four, up to three rounds, carrying only blocking questions. When blocking questions remain after the third round, stop, list them, and suggest Off Road; keep withholding the summary until each is answered or delegated.
    • Off Road: the unpaved road, for terrain the request does not yet map. On from the moment the user asks for it until this spec is approved, each round also carries the design choices you would otherwise settle alone, and you run as many rounds as the open points need, one theme each, until none is left. Before each round, survey the established options for its theme (libraries, approaches) and present them with their trade-offs and your recommendation. When the terrain needs study beyond this track, suggest ot-research and continue unless the user takes the suggestion. Approval ends Off Road; a spec returned to draft afterwards does not turn it back on unless the user asks again. Off Road adds no field to any artifact and does not carry across sessions: a new session starts with it off until the user asks again, even when a handoff quotes the earlier request.
  2. Write on-track/tracks/NNN-slug/spec.md from ./assets/spec.md bundled in this skill. Every constraint in the intent is binding, regardless of provenance. Outcome plus numbered Phases, Out of scope repeated from the intent without widening. Each phase separates the delivered state from its check: Done: names the delivered, observable state an observer can see when the phase closes, and Accept: names the check that proves it, a command with its expected result or an observable procedure with its expected observation. Files: is the explicit list of touched files. Auxiliary outputs go under assets/, never loose at the track root.
  3. Write tasks.md from ./assets/tasks.md bundled in this skill: organize tasks into named parallel groups using ## Group <name> headers, with (depends: <group>) on the header when a group depends on another. Tasks within one group touch disjoint files and have no data dependency, so they may run concurrently. When unsure about independence, use separate sequential groups. Each task line carries a (Phase N) tag naming the spec phase it serves, Files: for the files it touches, and Validate: naming a command with its expected result or an observable procedure with its expected observation. Include a task for each deferrable open question. When the user makes a qualifying decision, file on-track/decisions/<NNN-slug>.md from ./assets/decisions.md without a separate request and cite supporting refs, research, assessments, source URLs, or repository paths when available. Status is accepted | superseded only. Record evidence only in the ## Evidence body section; the ADR frontmatter has no evidence field. A decision qualifies only when BOTH hold: (1) it was a real choice, with at least one alternative weighed and rejected for a stated reason; (2) getting it wrong is expensive: reversing it takes more than reverting a diff (data migration, coordinated change in consumers, external commitment), or a future reader would likely undo it without the recorded reason. Durability alone, a restated user preference or instruction, and local, easily reversible, or obvious choices do not qualify. A user preference with no weighed alternative is a constraint in the intent, not an ADR. To replace an ADR: create the replacement as the next numbered accepted ADR, numbering after the highest number in on-track/decisions/ and on-track/decisions/archive/; set the original's status: superseded, add superseded_by: <replacement-id>, and move the original to on-track/decisions/archive/<NNN-slug>.md, leaving its decision text and other content unchanged. File outputs point under assets/.
  4. Regenerate on-track/INDEX.md with ../ot-init/scripts/on-track-index.sh <target> using the owner copy and report any validation error instead of presenting the summary as complete.
  5. Run ./scripts/on-track-gate.sh --mode structure --track NNN-slug --root <target> from this skill as an internal smoke test. Fix any gate failure before presenting the draft; structure mode ignores approval status and task checkboxes.
  6. Present a post-phase summary. Format:
    • Four short bullets: outcome, phases, task count, parallel groups.
    • Track location: on-track/tracks/NNN-slug/.
    • Next-step line: . para implementar. Before the track location and next-step line, list delegated decisions so the user can veto them, only when there are any.
Installs
11
First Seen
7 days ago