intent-packets

name	intent-packets
description	From the Intent Tree and Intent Compass, build the Packet Plan before proceeding to specification or direct implementation. Each packet has a parent intent and is behavior-preserving / testable / rollbackable. Does not implement.

intent-packets Skill

Core Mission

• Success Criteria:
  • There are as many packet candidates as the expected change size warrants (do not pad the count; one packet is fine for very small changes; treat 1–7 as a loose guide), and each packet references a parent intent
  • Each packet is drafted as an individual file under .intent/packets/active/ (1 packet = 1 file)
  • Each packet has Scope / Non-scope / Expected Behavior / Decisions / Safety(Invariants) / Validation / Evidence / Rollback / How to Proceed (keep Evidence as an empty section when there is no result)
  • In each packet's ## Decisions section, the common-core slots from decision-slots.md (plus the mode-specific diffs) are each closed with one of the 4 statuses (answered / undetermined / not-applicable / ADR candidate) (do not fill in defaults; do not silently skip)
  • Each packet is at a behavior-preserving / testable / rollbackable granularity
  • No existing packet file has been destroyed (changes are presented as differential update proposals)
  • No application code has been changed at all

Execution Steps

Step 1: Read the prerequisites

• Read .intent/intent-tree.md and .intent/intent-compass.md. If either is missing, guide the user to "run the corresponding command first" and stop.
• Check at the packets entry: check important decisions carried over from the Tree and Compass under the important-decision contract in CONTRACT.md. When a separate session starts from an existing packet, do not skip this entry check. If a decision has no allowed outcome, stop only the packets in the affected scope supported by evidence; drafting and review of unrelated packets may continue.
• While reading, when you see an unsettled verb slipped into the settled phrasing of the compass / intent-tree (assume / reuse / planned / TBD / tentative, etc.), do not fix it by guessing; present it as a conversion proposal into Open Questions or an undetermined slot (with the reason and the revisit condition (Revisit when)). Promotion to a fixed value is left to the user's confirmation. Do not re-convert spots already recorded in Open Questions / Deferred / an undetermined slot.
• Read the mode state in order: the inherited issue directory's discovery/<slug>-<rand>/mode.md (A34; inherit the issue name that discover output) → else the single .intent/mode.local.md (legacy) → else old .intent/mode.md (the CONTRACT.md read fallback contract). If both are absent, default to standard and announce it in Open Questions (do not stop).
• Read .intent/packets/index.md and the existing packet files under .intent/packets/active/ (the basis for differential updates).
• Legacy-install handling: if .intent/packets/, plan.md, index.md, or README.md is missing, the skill creates them itself before proceeding (do not wait for a scaffold reinstall).
• After-the-fact drafting (when implementation ran ahead): when the invocation context or the user's report makes clear that implementation proceeded / completed without a corresponding Packet, treat it with the same procedure as normal drafting (raise the Packet even after the fact; being already implemented is not a reason to skip drafting). In this case:
  • Record the established facts (the wiring / behavior already implemented) as what + constraints + oracle in the packet file.
  • For the spec that cannot yet be fixed (the trigger, threshold, judgment means, etc. — decisions not yet committed to, or placed provisionally), do not fill them by guessing; put them explicitly into the container as Open Questions and Deferred (undecided (deferred, with a revisit condition), always with the revisit condition). "Not drafting a Packet because the spec cannot be fixed" is wrong — holding the unfixed as-is is exactly the Packet's role.
  • Guide the order: first raise the Packet with this skill (the drafting phase), then return the learnings gained from the implementation reality to canonical via a delta with /intent-writeback (the post-implementation phase). These two run in opposite directions; do not perform only writeback while skipping the Packet drafting (the phase boundary follows writeback-protocol.md §3).

Step 2: Apply the mode definition's algorithm

• Open the mode definition that .intent/mode.local.md (falling back to .intent/mode.md) definition points to, and read and apply the algo rule (rules/algo-*.md) assigned to the Packet decomposition phase (standard → rules/algo-example-mapping.md; refactor → rules/algo-migration-slicing.md; behavior-unknown → rules/algo-example-mapping.md + rules/algo-characterization-test.md). The examples are not exhaustive; the mode definition's table is always authoritative.

Step 3: Decompose into Packets

• Following Example Mapping, expand each L2/L3 capability into "rules, examples, questions, deferred".
• Derive Expected Behavior, Validation, and Rollback from the examples.
• Consolidate into as many packets as the expected change size warrants (do not target a count or pad it; one packet is fine for very small changes; treat 1–7 as a loose guide). Measure size qualitatively by "the number of concerns touched × the breadth of impact on existing boundaries"; do not bring effort estimates or other numeric metrics into the slicing criteria (an estimate optionally written in the packet after slicing follows the "Estimate" section discipline in rules/packet-format.md — the set of range + grounds + implementer). Always give each packet a parent intent (a reference to L0/L1/L2/L3).
• Draft each packet as an individual file at .intent/packets/active/<packet_id>.md. Read rules/packet-format.md and follow it for ID assignment, filling in the frontmatter keys, and the body section structure (including the ## Decisions and ## Evidence sections) — the canonical source is the single source of truth for the key set and value domains.
• Stamp updated_at (the writer's responsibility): after writing a packet file, record its update timestamp in the frontmatter updated_at (ISO 8601). On a new packet, set updated_at to the same timestamp as created_at; when you change the content of an existing packet, update updated_at to that moment. On a re-run that involves no content change, do not change updated_at (idempotent; do not stamp when nothing changed). Obtain the timestamp with the shell date, the same way as created_at. If you cannot obtain the date/time, do not write a guessed date — report that instead. Stamping is the writer's (this skill's) responsibility and is not given to the read-only verification layer (intent-validate).
• Read rules/decision-slots.md and seed the completeness-schema slots into each packet's ## Decisions section (the canonical source for the slot definitions, value domains, and IDs is decision-slots.md; this section is its projection).
  • Seed the common-core slots (the 8 IDs seeded in every mode) into every packet, and add the mode-specific diff slots according to .intent/mode.local.md (falling back to .intent/mode.md) mode (standard / refactor / behavior-unknown / feature-growth). The slot definitions are authoritative in the decision-slots.md table; do not hardcode them into the SKILL body.

Step 4: Judge termination, then present priorities and splits

• Decomposition termination (composite stop condition): stop splitting once a packet satisfies all six conditions. (1) one packet maps to one primary concern; (2) the acceptance criteria reduce to observable inputs, conditions, and expected results; (3) the boundaries of the solution space (fixed / discretionary / forbidden) are explicit; (4) cheap-to-reverse (backing out is cheap); (5) the trace target is clear (you can follow the parent intent / spec_refs); (6) standalone completeness: a packet's own done is a coherent behavioral boundary that is not half-baked as seen by the user / caller (do not create a done for half-done behavior). (6) is an independent condition distinct from (4) — (4) is "the builder-side rollback safety (intermediate states can be backed out)", while (6) is "the caller-side semantic consistency of the completed form"; the observer differs (do not fold (6) into (4)). Before these hold it is too coarse; splitting further after they hold is over-decomposition.
• The verifiability floor is discriminative testability: "a test can be written (testability)" is not enough; there must be "an oracle that can reject a wrong implementation". A packet for which no such rejecting oracle can be found has immature acceptance criteria — rework its Validation / Expected Behavior into observable form.
• A packet whose acceptance criteria span multiple concerns or multiple quality-attribute trade-offs is judged "still too coarse"; propose splitting it along concern lines (move toward one packet = one concern).
• Do not decompose a work unit down to implementation steps (a full specification of the how). Keep it at what + constraints + oracle (what / boundary constraints / an oracle that rejects wrong implementations), and leave the inside of the rules to the agent's discretion.
• Maintain the existing granularity discipline (behavior-preserving / testable / rollbackable; the count is variable with the change size, with 1–7 as a loose guide, and do not pad the count), and use "one packet = one concern" and (6) standalone completeness explicitly in the termination judgment.
• Indicate the packets' priority.
• Read rules/walking-skeleton.md and apply it according to the rule's applicability conditions.
• Read rules/first-packet.md and apply it.
• Read rules/journey-plan.md and apply it (only for a multi-packet case, propose drafting a journey — a unit bundling multiple packets — to the user; for a single-packet case or an environment without the journeys/ conventions it does not fire and everything proceeds as before).
• Present split proposals for packets that are too large.
• For packets confirmed by the user, declaratively update state from draft to ready (ready to start; dependencies resolved) and regenerate (see for the value domain and the regeneration procedure). However, when an undecided slot is an important decision, do not mark its packet . Present the affected packet and the evidence for the effect, obtain an allowed outcome defined by , then recheck the affected artifacts and resume only the affected scope. When an undecided slot is not an important decision, it is not by itself a reason to stop readiness or stage progress. Progression to in-progress/awaiting-verification/done (//) is done by subsequent declarations based on a human or a check gate.

Output Description

Reader: the human developer carving out work units and handing them to the implementation flow. What this output makes them grasp first: "The packet to start with first is this (= the packet to export next). The next move is the exit that matches the case type." The packet list, priorities, and split proposals are the supporting detail.

Lead with the conclusion (the packet to start and the next command).

• The packet to start with first (first, with reasons): the recommended packet = the packet to export next (the same one). Add why it is placed first.
• Next move (one line, branched by case type): apply rules/export-route.md (the exit decision lane) read-only and present the exit chosen from the case type. Do not recommend cc-sdd unconditionally (no hardcoding):
  • If the target format (the format line in .intent/mode.local.md) is set to a valid value, recommend that exit: cc-sdd → /intent-export-cc-sdd / openspec → /intent-export-openspec / speckit → /intent-export-speckit / to-spec → /intent-to-spec / direct → direct implementation (no exit command).
  • If format is unspecified (absent / placeholder / out of range), infer the candidates from mode (non-code / standard-family) and the setup markers of the downstream spec tools (presence of .kiro/ / a repository-root openspec/ / a repository-root .specify/; read-only observation). For an implementation case, list the set-up tools first and the not-set-up ones afterwards with a "needs setup" note, attaching the one-line fit note for each exit. For non-code, put /intent-to-spec at the top of the candidates.
  • Setup status is observation and annotation, not a gate (never drop a not-set-up candidate; never stop). Even when several are set up, do not invent a priority — keep listing candidates and let the human choose. When it cannot be uniquely determined, likewise do not collapse to a single exit (the exit depends on the user's intent; the convention for markers/ordering/notes/fit notes and the decision detail are owned solely by rules/export-route.md — do not copy them into this file).
• Details: the packet files under .intent/packets/active/ (new drafts and differential update proposals for existing ones; as many packets as the change size warrants, with 1–7 as a loose guide, each with a parent intent), updates to .intent/packets/plan.md and .intent/packets/index.md, packet priorities, and split proposals for packets that are too large.
• Handoff guidance (optional, one trailing line; INV82-(2)/DR143): packets is a work break, so at the end of the output you may add exactly one read-only guidance line to the effect of "You can continue to implementation (the exit) as is, or hand the work over to a new session here." (Optional; put the conclusion [the choices] first = bluf.) (a work break AND the sense of length; stay silent in a short session). Before adding it, also weigh the trade-off (DR159): (1) the nature of the remaining work — do design decisions remain, or is it just doing what is already written; (2) how much session-specific tacit knowledge would be lost by handing over; (3) how natural this break point is. If the estimate is that not handing over is the better deal, do not recommend switching — stay silent (or add one line that continuing is the better deal). When you cannot estimate, lean toward staying silent. When you do recommend switching, attach the estimate as one qualitative line (no numbers). Do not read the conversation log or token amount, and emit no numbers (INV82-(2); the INV22 constraint). Only when a compatibility-verified skill is available on the current agent surface, tell the user they can ask to “write a handoff document with ”. When the skill is not installed, incompatible, or verification fails, do not emit any generation guidance; degrade silently without an internal generator or overview fallback. It never cuts the session automatically, never writes out a brief on its own, and never corrects "continue" (the next move = the exit guidance is unchanged).

Plainness check for reports (user-facing reports; right before output; shared)

Right before emitting a user-facing report (progress, completion, items needing confirmation — including the end-of-turn summary), run this check (INV105, DR208). It applies only to user-facing report text, not to how internal records (canonical files and logs under .intent/) are written.

• Do not transcribe internal documents verbatim: text you just read or wrote in internal artifacts (tree, compass, packets, Open Questions) is written in internal vocabulary. In the report, restate that content in words a first-time reader understands (without changing facts or meaning).
• Identifiers must not be the subject of the sentence: when presenting an item to confirm or a unit of work, first write one sentence that stands on its own ("what and why"), then append identifiers (Open Question numbers, packet names, symbols, stage names) after it as references (e.g. "... please verify this before starting (ref: OQ-xxx-1)"). Do not delete identifiers or references to records for the sake of plainness (the trail back to the record is lost).
• Signal for overload: three or more unexplained internal terms in one sentence signal overload (read by meaning, not by mechanical count). If a sentence does not stand on its own, rewrite it in plain words before sending (without changing facts or meaning).
• Do not convey meaning only through a metaphor or a vague qualifier: the foundation of a report is precision — write so the meaning reads unambiguously (plain language is a means of staying easy to read while preserving it). Do not report results only with ungrounded qualifiers (e.g. "significantly", "nicely"); state observable facts. If you use a metaphor, pair it immediately with a precise restatement (do not force established technical terms, or ordinary words in their everyday sense, into strained paraphrases).
• This check works as a pair with the after-the-fact record (prevention alone is never enough): when a report failed to get through, log the case to the drift log while drift-watch is on, and feed the next prevention.

Safety & Fallback

• If there is no Intent Tree / Compass, stop and guide the user to the corresponding command.
• The absence of mode.md does not stop; continue with the standard default and announce it.
• Do not drop packets too far down into implementation tasks (above an Issue, before a spec).
• Do not delete packet files (move only).
• Shell command usage is limited to getting the date/time, directory creation (mkdir) and moves under .intent/packets/ (the invariant of not changing application code stays).
• Do not change application code.