Jira align brief intake

Skill: jira-align-brief-intake

This is choreography, not invention. It composes two things that already exist:

• jira-align skill (sibling in this pack) — all Jira Align reads. You never write a raw Jira Align REST call here and never invoke a write verb.
• receive-brief skill (shipped by the host repo; resolved by name through the harness) — owns Elicit (fill missing Outcome/Scope conversationally), Decompose (cut into shippable slices), and Execute (chain new-spec → work-loop). This skill does not reimplement elicitation; it hands off the assembled brief and steps back.

If you find yourself writing a Jira Align REST call or interrogating the user for missing Outcome/Scope fields, stop — the right place is one of the two above.

One-time setup: customise the field mapping

Before first use on a new Jira Align instance, open references/field-mapping.md and fill in:

1. Workflow state vocabulary — your instance's state names in the "Customize for your org" table. Standard names (Planned, In Progress, Completed) are pre-filled; replace or extend them.
2. PI naming pattern — the cadence label format your org uses (e.g., PI 2026-Q1, PI 24).

This is a one-time step per instance. The brief this skill produces will be wrong in the State context sentence if the state names don't match.

Cross-skill invocation — name, not path

This skill names sibling skills (jira-align) and host skills (receive-brief) by their name: field, never by path. Install locations vary by IDE and scope. The contract: when this skill says "via the jira-align skill: get features <ID> …", the agent uses its native skill-dispatch mechanism to invoke the skill registered under that name with those arguments.

Install guidance for the named dependencies lives in manifest.json under deps.skills — that's a where to get them hint, not a runtime path.

Prerequisites

Before Stage 1, confirm:

1. The jira-align skill is installed and reachable. Invoke it: jira-align: check. Exit 0 → proceed. Exit 2 → tell the user to run credential-setup themselves (interactive — they run it, not you) and stop. jira-align is a hard dependency; there is no degraded path without it.
2. The receive-brief skill is installed (from agent-ready-repo or wherever the consumer keeps it). If not, note the absence — do not stop. The core-absent branch in Stage 4 handles this gracefully.

Lifecycle

Stage 1 — Intake

Fetch the Feature with all fields needed to populate the brief, via the jira-align skill:

jira-align: get features <ID> --expand ownerUser,milestones

Check for the three intake requirements of a Feature:

Requirement	Where it lives in Jira Align
Title (what this feature delivers)	title field
Description or scope notes	description and/or notes fields
Owner / program context	ownerUser (expanded), programID

When any requirement is missing or empty, note the gap — don't stop. receive-brief elicits what's missing in Stage 4.

Stage 2 — Enumerate children

Fetch the Feature's child items by resource type:

jira-align: list stories --filter "featureID eq <ID>"
jira-align: list tasks --filter "featureID eq <ID>"
jira-align: list defects --filter "featureID eq <ID>"

Collect whichever resource types return results. A Feature with no children is valid but thin — ask the user before proceeding (see Boundaries: Ask first).

For each child item, record:

• Resource type: stories, tasks, or defects
• id
• title (the story text)

Stage 3 — Map fields to brief

Using references/field-mapping.md as your guide, map the fetched data onto the Shape B brief template.

Heading and provenance:

# Brief: <Feature title>

- **Slug:** `<kebab-case-slug>` (derive from the Feature title)
- **Received:** <today's date>
- **Owner:** <owner from ownerUser, or ask>
- **Status:** Draft
- **Epic:** <JIRAALIGN_BASE_URL>/features/<ID>

Outcome (load-bearing — do not leave empty):

Combine description and notes into one paragraph. When both are present, lead with the description and append notes as context. When only one is present, use it. When neither is present, write [Outcome not provided — receive-brief will elicit] as a placeholder; do not invent.

Then append a one-line state context sentence using the mapping in references/field-mapping.md's state vocabulary table:

*(Current state: <state value> — <Brief handling from your org's mapping>)*

Example: *(Current state: In Progress — active delivery)*. When state is absent from the Feature response, omit the line.

Scope / In scope:

When acceptanceCriteria is present on the Feature, use it as the In scope prose. Otherwise leave the heading with an empty placeholder; receive-brief elicits it.

User stories (Shape B):

Map each child to a US-n story line. The format is pinned:

- **US-n.** (stories/<id>) <story text>

Substitute tasks/ or defects/ for the resource type. For <story text>:

• Reshape the child's title into the As a … / I want … / so that … grammar when the title itself contains a role and benefit (e.g. "As a PM, track sprint velocity…"). Do not invent a role that isn't in the title.
• Carry the title verbatim when a role/benefit cannot be inferred — do not invent. receive-brief refines during Elicit.

The US-n index is sequential across all resource types, ordered by: stories first, then tasks, then defects.

Program Increment context (optional):

When milestones expands to a PI record, add a one-line note in the brief's ## Context section (add the heading if absent):

> **Program Increment:** <PI name from milestones> — carry forward as
> appetite signal; confirm with `receive-brief`.

Stage 4 — Write brief and hand off

Write the assembled brief to docs/product/briefs/<slug>.md. If the file already exists, ask the user whether to merge or replace before writing.

Core-present path (receive-brief installed):

Hand off to receive-brief by name:

receive-brief: docs/product/briefs/<slug>.md

receive-brief elicits missing fields (Outcome gaps, Scope, Success metrics, Appetite), runs DoR, decomposes, and chains into new-spec → work-loop. Your role ends at the hand-off.

Core-absent path (receive-brief not installed):

When receive-brief is unavailable, inline the following instruction and act on it directly:

Core-absent brief — act on this directly:

The brief at docs/product/briefs/<slug>.md is assembled from Jira Align data. Proceed as follows:

1. Elicit missing fields. Ask the user to fill in any empty headings in the brief (Outcome gaps, Success metrics, Scope, Appetite).
2. Decompose. For each US-n story that warrants its own spec, open docs/specs/<feature-slug>/spec.md and ask the user to confirm the decomposition before proceeding.
3. Execute. For each confirmed spec, invoke new-spec by name (if installed), then work-loop. If neither is installed, tell the user which packs to install and stop.

Don't

• Don't read ~/.agentbundle/credentials.env from the skill body.
• Don't write a raw Jira Align REST call — use the jira-align skill.
• Don't invoke create, update, delete, or raw with a mutating method on the jira-align skill. Intake is read-only.
• Don't re-run credential-setup for the user or pipe the token into it.
• Don't reimplement receive-brief's elicitation — hand off and step back.
• Don't invent Outcome, Scope, or story text the Jira Align source doesn't support. Surface the gap; let receive-brief elicit it.
• Don't reference this skill, jira-align, or receive-brief by path — always by name.
• Don't claim portability across all Jira Align instances without asking the adopter to customise references/field-mapping.md first.

Edge cases

• Feature not found (404): the jira-align CLI exits 3 and prints the server message. Surface it to the user and stop — do not guess or substitute.
• Credentials missing / expired (exit 2): tell the user to re-run credential-setup and regenerate their API token on the Jira Align Profile page.
• Feature with no children: confirm with the user before assembling a brief from title + description alone — a Feature with no stories is unusual and may indicate the wrong ID or incomplete Jira Align data.
• Custom fields: Jira Align instances expose org-specific fields in responses. When a field named in references/field-mapping.md's "Customize for your org" section is present in the Feature response, use it. When it is absent, skip it and note the gap in the brief.
• Large child sets (> 100): the jira-align CLI paginates transparently up to --limit. For features with many children, consider scoping the intake to a representative subset and noting the total count in the brief; confirm with the user.