codingthefuturewithai/teamcraft-auto:plan-iteration

Goal

A backlog is a pile of work. An iteration is a decision: for the next fixed window, with the people and time you actually have, here is the one goal you're committing to and the specific, sequenced set of work items that serves it. This skill runs that decision with the developer — and writes the result onto the work items as a durable iteration label, so the rest of Teamcraft (the build loop, the work board, project status, retros) can see what's committed.

This is deliberately more than walking the feature list and calling create-issue N times. Planning is a conversation the feature list can't have on its own:

• What's the goal of this iteration? Not "do some items" — the outcome that makes the window a success.
• How long is the window, and when? One week, two weeks, a month.
• How much capacity? How many people, how much of their time, and what past throughput suggests is realistic.
• Given all that, what actually fits — and in what order? Honoring dependencies, and leaving out what won't fit, on purpose.

Read references/example-iteration-plan.md first — it shows the planning conversation, the proposed plan, and exactly what gets written to the work items.

How an iteration is represented

Two parts, each with a single source of truth — nothing is stored twice:

• Membership lives on the work items. Every item in the iteration carries the same iteration: value in its frontmatter — a label the developer chooses (2026-S24, onboarding-v2, cycle-3; their scheme, not ours). An item with no iteration: field is simply unassigned.
• The iteration itself is a small file, .teamcraft/iterations/<label>.md, holding the iteration-level facts that don't belong on any one item: the goal, the window (start/end), capacity, and status (active/closed). Structured frontmatter, so status and retros can read it directly.

The iteration file does not list its members — membership is derived by scanning item frontmatter for the label, the same one-way principle Teamcraft uses for relationships (blocked_by is stored; blocks is computed on read). One source of truth each means the two can't drift. Create .teamcraft/iterations/ on first use if it isn't there.

Establish Intent

Iteration planning isn't one situation. Ask which this is, because the flow differs:

1. First iteration on a new project — backlog may be empty or sparse; the PRD (and roadmap, if there is one) is the primary input; some work items may need to be created as part of planning.
2. Next iteration on an ongoing project — plan from the existing backlog; carry over anything unfinished from the current iteration.
3. Adjust the current iteration mid-flight — scope changed; add, drop, or resequence items already committed without disturbing what's in progress.
4. Review the current iteration — just show what's committed, the goal, and how it's tracking (then hand off to project-status for the live read).

Gather the Inputs

Works at any project state — a polished PRD with a roadmap, or nothing but a verbal goal in an empty repo. Assume nothing exists; offer to create what's missing.

• Existing work. Glob .teamcraft/work/, read INDEX.md and the items. Note each item's status, priority, effort, blocked_by, and any iteration label already set — so you carry over unfinished work and never double-assign an item that's mid-flight.
• Existing iterations. Glob .teamcraft/iterations/. An active one tells you what's currently committed, its goal, and what's still unfinished to carry forward. None is fine — this may be the first.
• Requirements context (optional). If a PRD exists, skim only the sections relevant to the stated goal — for acceptance context, not a full read. If there's no PRD, don't block; the developer's description of the goal is enough to plan against.
• Past throughput (optional). If completed items carry started/completed dates, they reveal the team's real pace. Use that to sanity-check capacity rather than guessing — but it's context, not a gate.

Run the Planning Conversation

Gather the collective context the feature list can't supply. Keep it conversational, not an interrogation:

• the iteration goal — the outcome that defines success for this window;
• the window — duration, and start/end dates if they have them;
• the capacity — how many people and roughly how much of their time; if throughput history exists, offer what it suggests as a reality check ("last two windows you closed ~6 medium items each").

The developer owns all three. Your job is to make the trade-offs visible, not to decide for them.

Assemble the Plan

From the candidate work items, propose a set that serves the goal and fits capacity:

• Serves the goal first. Pull items that move the stated outcome. A high-priority item unrelated to this iteration's goal can wait for the next window — say so explicitly rather than pulling it just because it's high priority.
• Respect dependencies. Don't schedule an item ahead of a blocked_by that is neither already done nor sequenced earlier in this same iteration. Order the set so blockers land before the work they gate.
• Size honestly against capacity. Use effort estimates as a guide and apply judgment — the goal is a set the team can actually finish with a little air, not a stuffed list that slips. Name what you're leaving out and why. Remember each item carries Definition-of-Done overhead (../references/definition-of-done.md) — tests and docs, not just feature code — so an estimate that counts only the feature work will overcommit.
• Create the items the iteration needs, when they don't exist. Greenfield, or a PRD with no issues yet: the items to plan may not exist. Draft each missing one as a full work item per the work-item standard (../references/work-item-standard.md) — title, why, acceptance criteria, priority, effort, iteration set from the start — sourced from the goal and the relevant PRD sections. Show them to the developer for review alongside the rest of the plan, then write and commit them. No stubs, no lighter version, and never hand item creation back to the developer to do separately — drafting these to standard is part of planning.

Present for Approval

Show the full plan before writing anything: the goal, the window, the ordered item list with efforts, the total against capacity, and what you deliberately left out (and why). The developer adjusts — add, drop, reorder, resize — until they approve. Assign nothing until they say yes; planning proposes, the developer commits.

Write the Iteration

On approval:

• Label each member item. Set iteration: <label> in the frontmatter of every item in the set. Edit existing items; on items you just created for this iteration, include it from the start. Don't touch items that aren't in the iteration.
• Write the iteration file. Create or update .teamcraft/iterations/<label>.md — frontmatter with the goal, start/end, capacity, and status: active; a short prose statement of the goal in the body. Don't list members here; they're derived from the item labels. Keep it light — no certification stamp (iteration files are operational planning artifacts, like work items, not captured knowledge).
• Close out the iteration this replaces. If you're planning the next iteration and an active one already exists, ask whether to mark it status: closed. Carry any unfinished items forward deliberately (see the constraint below) rather than stranding them under a closed label.
• Commit after approval, with the iteration label in the message (e.g., chore(2026-S24): plan iteration).

Respect Domain Ownership

This skill plans an iteration. It does not author requirements (capture-requirements), capture architecture or tech decisions (capture-technical-design), implement work (build-issue), or pick the single next item to build right now (pick-next-issue). It does create the iteration's work items to the work-item standard when they don't exist yet — that's part of planning, not a separate step the developer runs. create-issue remains the standalone entry point a developer reaches for when they already have a one-off feature or bug in mind, outside planning. If the conversation drifts, note it and redirect.

Constraints

• Nothing enters an iteration without the developer's yes. Planning proposes; the developer commits.
• Don't yank in-flight or done work. When re-planning, carry over unfinished items deliberately; never silently drop or reassign an item someone is partway through.
• Capacity is judgment, not arithmetic. Effort estimates inform the call; they don't make it. A plan that just sums points and stops is exactly the kind of planning this skill exists to replace.
• Works at any project state. An empty repo with a verbal goal, or a mature backlog mid-project — both are valid entry points.

When You're Done

Confirm the iteration label, the goal, the window, and the items assigned. Point to the natural next steps: /pick-next-issue or /build-issue <id> to start building, and /work-board or /project-status to track the iteration as it runs.