x-internal-create-epic
Generate an Epic document from spec analysis or from an existing Feature artifact: cross-cutting rules, story index, DoR/DoD, optional Jira, sourceFeature lineage, and inherited RNFs. Invoked by orchestrators and focused public wrappers. Not user-invocable.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-internal-create-epic
- model
- sonnet
- visibility
- internal
- description
- Generate an Epic document from spec analysis or from an existing Feature artifact: cross-cutting rules, story index, DoR/DoD, optional Jira, sourceFeature lineage, and inherited RNFs. Invoked by orchestrators and focused public wrappers. Not user-invocable.
- allowed-tools
- Read, Write, Edit, Bash, Grep, Glob, AskUserQuestion, Skill
- context-budget
- medium
- user-invocable
- false
- requires-capabilities
- []
02 资源文件 1
- 参考文档README.md1.8 KB
03 SKILL.md 正文
🔒 INTERNAL SKILL — Invoked only by other skills via the Skill tool. Not user-invocable.
Output Policy
- Language: Portuguese (pt-BR) for all content. English for technical terms (cache, timeout, handler, endpoint) and code identifiers.
- Tone: Technical, Direct, and Concise.
- Efficiency: Remove all conversational fillers and greetings to save tokens.
Skill: Epic Generator
Purpose
Read a system specification document or an existing Feature artifact and generate an Epic file — the top-level artifact that defines scope, cross-cutting rules, quality criteria, and story index for a development effort. The Epic is the single source of truth for a decomposition: it captures rules spanning multiple stories, defines quality gates, and provides the complete story index with dependency relationships.
Triggers
/x-epic-create <spec_file>— generate an epic from the specification/x-epic-create --from-feature <feature-file|feature-id>— generate an epic from an existing feature artifact- User asks to create an epic, generate an epic from a spec, or decompose a specification into an epic
- User mentions extracting cross-cutting rules, defining quality gates, or building a story backlog from a technical document
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
<SPEC_FILE> |
Path | Yes | — | Path to the system specification file |
--from-feature <feature-file|feature-id> |
String | No | — | Feature artifact source for Product-First Feature → Epic generation |
--capability-file <path> |
Path | No | — | Capability artifact used to enrich inherited RNFs in --from-feature mode |
--product-file <path> |
Path | No | — | Product artifact used to enrich inherited RNFs in --from-feature mode |
--epic-id |
String | No | auto | Epic number (auto-increments from existing epics in plans/) |
--jira |
String | No | — | Jira project key (e.g., PROJ). When provided, skip AskUserQuestion and create in Jira directly (EPIC-0042). |
--no-jira |
Boolean | No | false | Skip Jira integration entirely, no prompting (EPIC-0042). |
--dry-run |
Boolean | No | false | When true, artifacts are written to disk but Steps P4 / P5 (planning-commit / push) become no-ops with a "dry-run, skipping commit" warning (EPIC-0049 / RULE-007). |
--legacy-template-v1 |
Boolean | No | false | DEPRECATED (Rule 19 §Skill Renaming — removed in 2 releases). Use v1 template structure. Emits deprecation warning on stderr on every invocation. |
Prerequisites
Read the following files before starting:
Template (output structure):
.claude/templates/_TEMPLATE-EPIC.md— The exact structure to follow (v2 value-driven: 9 sections + Refinement Verdict). Default. When--legacy-template-v1is set, use v1 structure instead and emit the deprecation warning below.
Decomposition philosophy (how to identify stories and rules):
.claude/skills/x-epic-decompose/references/decomposition-guide.md
If any template file is missing, stop and tell the user. The templates define the output structure and must be read fresh from disk every time (never hardcode the structure).
v2 value-driven guidance (EPIC-0070): When generating the epic with the default template, explicitly fill:
- Section 3 (Hipótese & OKRs): State the value hypothesis in
Se…então…porqueform + at least 1 OKR/KPI with unit and measurement method.- Section 4 (Alternativas Consideradas): At least 2 alternatives with rejection rationale (
Decisão de rejeição:marker).- Section 5 (Escopo): In-scope list AND out-of-scope list; out-of-scope ≥ 3 items.
--legacy-template-v1deprecation warning: When the flag is present, emit to stderr before writing the file:WARN [legacy-template] --legacy-template-v1 is DEPRECATED. Templates v1 will be removed in 2 releases. Migrate to v2: /x-migrate-templates <epic-id>
Workflow
Step P1 — Detect Worktree Context (EPIC-0049 / RULE-001)
<!-- TELEMETRY: phase.start -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-epic-create Phase-P1-Worktree-Detect
Invoke x-manage-worktrees in detect-context mode to record whether the current checkout is already inside an epic worktree (STORY_OWNS_WORKTREE=false, EPIC_WORKTREE_DETECTED=true|false). Result is advisory only — x-internal-ensure-epic-branch (Step P2) makes the authoritative decision.
Skill(skill: "x-manage-worktrees", args: "detect-context")
Continue on any detect-context failure (fail-open, RULE-006) — log a WARNING and proceed to Step P2.
<!-- TELEMETRY: phase.end -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-epic-create Phase-P1-Worktree-Detect ok
Step P2 — Ensure epic/<ID> Branch (EPIC-0049 / RULE-001)
<!-- TELEMETRY: phase.start -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-epic-create Phase-P2-Epic-Branch-Ensure
Resolve the effective --epic-id:
- If
--epic-idwas provided, use it verbatim (4-digit regex validated by Step 5). - Otherwise, scan
plans/for existingepic-XXXXfolders and pick the next available number (default0001if none). Set this as the effective epic ID for both P2 and P4.
Invoke x-internal-ensure-epic-branch so the canonical epic/<ID> branch exists locally AND on origin (idempotent). The skill is a no-op when the current checkout is already on epic/<ID> or a worktree rooted at that branch.
Skill(skill: "x-internal-ensure-epic-branch", args: "--epic-id <XXXX>")
On failure (non-zero exit), abort with EPIC_BRANCH_ENSURE_FAILED — a clean audit trail cannot be produced without the canonical branch.
<!-- TELEMETRY: phase.end -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-epic-create Phase-P2-Epic-Branch-Ensure ok
Step 1 — Read the Input Spec
<!-- TELEMETRY: phase.start -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-epic-create Phase-1-Spec-Analysis
Read the entire source artifact provided by the user.
- Spec mode (default): the file follows
_TEMPLATE.mdwith sections like Overview, Business Rules, Platform Specs, Data Contracts, Journeys, Dependencies, and Interfaces. - Feature mode (
--from-feature): the file is an existing Feature markdown artifact. In this mode, preserveSource Feature, load inherited RNFs from Feature → Capability → Product, and intentionally omit sections2,4, and8from the generated epic because that context already exists upstream in the Product-First chain.
Understand the full source scope before starting extraction.
<!-- TELEMETRY: phase.end -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-epic-create Phase-1-Spec-Analysis ok
Step 2 — Extract Cross-Cutting Business Rules
<!-- TELEMETRY: phase.start -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-epic-create Phase-2-Rules-Extraction
Scan the spec for business rules that apply to more than one journey or operation. These become the Epic's Rules table with unique IDs (RULE-001, RULE-002, ...).
What qualifies as a cross-cutting rule:
- A decision logic that affects multiple journeys (e.g., "cents-based approval applies to all transaction types")
- A platform-wide constraint (e.g., "idempotency key required on all mutations")
- A behavioral policy (e.g., "timeout handling: N seconds sleep before response")
- A validation that gates multiple operations (e.g., "entity must be active for any operation")
What stays in individual stories:
- Rules that apply to only one journey (e.g., "bulk import only allowed via async endpoint")
- Implementation details specific to one handler
Each rule gets a description detailed enough that a developer can implement it without going
back to the spec. Use <br> for line breaks within table cells. Include priority/precedence
when rules can conflict.
TDD cross-cutting rules: When the spec describes a system that follows TDD practices, extract these as cross-cutting rules:
- Red-Green-Refactor: Mandatory cycle for all production code — write failing test, make it pass, refactor
- Atomic TDD Commits: Each Red-Green-Refactor cycle produces atomic commits with Conventional Commits format
- Gherkin Completeness: Every acceptance criterion must have corresponding Gherkin scenarios
<!-- TELEMETRY: phase.end -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-epic-create Phase-2-Rules-Extraction ok
Step 3 — Identify Stories
<!-- TELEMETRY: phase.start -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-epic-create Phase-3-Story-Index
Read the decomposition guide (x-epic-decompose/references/decomposition-guide.md) for
the layer-by-layer approach. In summary:
- Foundation (Layer 0): Infrastructure stories — servers, schemas, base APIs, protocol adapters
- Core Domain (Layer 1): The central operation that establishes architectural patterns
- Extensions (Layer 2): Additional operations reusing core patterns
- Compositions (Layer 3): Stories combining multiple extension capabilities
- Cross-Cutting (Layer 4): Testing, observability, security, tech debt
For each story, determine:
- Title: Concise, action-oriented (e.g., "Infraestrutura Socket e Echo Test (1804)")
- Blocked By: Which stories must be done first (structural, data, or pattern dependencies)
- Blocks: Which stories depend on this one
Validate the dependency graph: no circular dependencies, every extension depends on the core, compositions depend on their constituent extensions.
<!-- TELEMETRY: phase.end -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-epic-create Phase-3-Story-Index ok
Step 4 — Define Quality Criteria
<!-- TELEMETRY: phase.start -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-epic-create Phase-4-Epic-Generation
Global Definition of Ready (DoR): Extract from the spec's quality requirements, or derive sensible defaults:
- Technical specifications validated
- Dependencies resolved
- Data contracts reviewed
Global Definition of Done (DoD): Extract from the spec, or derive from the tech stack:
- Coverage targets (line, branch)
- Required test types (unit, integration, E2E)
- Documentation requirements
- Performance SLOs
- Persistence/data integrity criteria
- TDD Compliance: commits show test-first pattern (test precedes implementation in git log), explicit refactoring after green, tests are incremental (simple to complex via Transformation Priority Premise)
- Double-Loop TDD: acceptance tests derived from Gherkin scenarios (outer loop), unit tests guided by Transformation Priority Premise (inner loop)
Step 5 — Generate the Epic File
Write the Epic following the _TEMPLATE-EPIC.md structure exactly.
v2 sections (default — EPIC-0070):
- Header: ID, Status (
Em Refinamento), Refinement Verdict (TBDinitially) - Section 1 — Visão & Problema: Scope + observed pain point from spec's Overview
- Section 2 — Persona & Stakeholders: Who is affected and how (specific role, not "o sistema")
- Section 3 — Hipótese & OKRs: Value hypothesis in
Se…então…porqueform + ≥1 OKR/KPI with unit and measurement method - Section 4 — Alternativas Consideradas: ≥2 alternatives with rejection rationale (
Decisão de rejeição:) - Section 5 — Escopo: In-scope list AND out-of-scope list (out-of-scope ≥3 items)
- Section 6 — Riscos: ≥1 product risk + ≥1 technical risk with mitigation
- Section 7 — Índice de Histórias: Story index from Step 3, with links, dependencies, and measurable value per story
- Section 8 — Quality Gates: DoR/DoD from Step 4
- Refinement Verdict block:
Status: TBD, all dimensions unchecked
When --legacy-template-v1 is used:
Emit the deprecation warning (see Prerequisites), then use v1 structure: Visao Geral, Anexos e Referencias, Definicoes de Qualidade Globais, Regras de Negocio Transversais, Indice de Historias. Emit telemetry event metadata: {flag: "legacy-template-v1", skill: "x-epic-create"} for adoption tracking.
Directory and file naming (mandatory — see SD-09 in decomposition guide):
- Determine the epic number: scan
plans/for existingepic-XXXXfolders and use the next available number (default0001if none exist). Ask the user if unsure. - Create the directory
ai/epics/epic-XXXX/ - Save the Epic file as
ai/epics/epic-XXXX/epic-XXXX.md - Story IDs in the index use composite format:
story-XXXX-YYYY(where XXXX = epic number, YYYY = story sequence) - Story links in the index point to
./story-XXXX-YYYY.md(relative to the epic folder)
Step 6 — Optional Jira Integration
After generating the Epic file content but before the final save, optionally create the Epic in Jira.
6.1 — Check MCP Availability
Verify that the Jira MCP tool (mcp__atlassian__createJiraIssue) is available.
If not available, skip this entire step silently and proceed to Step 7.
6.2 — Check Context and Flags (EPIC-0042)
Roteamento por flag (EPIC-0042):
-
Se
--no-jiraestiver presente: pular a integracao com Jira completamente. Substituir<CHAVE-JIRA>por—e prosseguir para o Step 7. Log:"Jira integration skipped (--no-jira, EPIC-0042)" -
Se
--jira <PROJECT_KEY>estiver presente: usar a chave de projeto fornecida diretamente. Pular AskUserQuestion. Descobrir ocloudIdchamandomcp__atlassian__getAccessibleAtlassianResources. Usar oiddo primeiro site disponivel comocloudId. Se a chamada falhar ou nao retornar sites, alertar o usuario e pular para o Step 7 (substituir<CHAVE-JIRA>por—). Caso contrario, prosseguir para 6.4. Log:"Jira integration via --jira flag: project {PROJECT_KEY} (EPIC-0042)" -
Se esta skill foi invocada pelo orquestrador (
x-epic-decompose) e umjiraContextja foi fornecido, usar esse contexto diretamente (pular o prompt ao usuario — ja foi perguntado na Phase A.5). SejiraContext.enabled == true, prosseguir para 6.4. Sefalse, pular. -
Se invocada standalone (sem
jiraContext, sem--jira, sem--no-jira), prosseguir para 6.3 para o prompt interativo compativel com a versao anterior.
6.3 — Ask the User (standalone invocation only, no flags)
Use the AskUserQuestion tool:
question: "Deseja criar este epico no Jira?"
header: "Jira"
options:
- label: "Sim, criar no Jira"
description: "Criar o epico como issue no Jira via MCP e preencher a Chave Jira no markdown"
- label: "Nao, apenas markdown"
description: "Gerar apenas o arquivo markdown sem integracao com Jira"
multiSelect: false
If "Sim":
- Ask for the Jira project key:
question: "Qual a chave do projeto Jira? (ex: PROJ, MYAPP, TEAM)" header: "Projeto" - Discover the
cloudIdby callingmcp__atlassian__getAccessibleAtlassianResources. Use the first available site'sidas thecloudId. If the call fails or returns no sites, warn the user and skip to Step 7 (replace<CHAVE-JIRA>with—).
If "Nao": replace <CHAVE-JIRA> with — and proceed to Step 7.
6.4 — Create Epic in Jira
Call mcp__atlassian__createJiraIssue to create an Epic issue:
cloudId: the discoveredcloudId(orjiraContext.cloudId)projectKey: the user-provided project key (orjiraContext.projectKey)issueTypeName: "Epic"summary: the Epic title from the generated headerdescription: the "Visao Geral" section textcontentFormat: "markdown"additional_fields:{ "labels": [{ "name": "generated-by-ia-dev-env" }, { "name": "epic-XXXX" }] }
Where epic-XXXX is the local epic ID (e.g., epic-0012) for bidirectional ID sync.
Capture the returned Jira issue key (e.g., "PROJ-123").
6.5 — Update Markdown
Replace <CHAVE-JIRA> in the generated Epic markdown with the actual Jira key.
Report: "Epico criado no Jira: PROJ-123"
6.6 — Jira Error Handling
If the Jira MCP tool call fails:
- Warn the user with the error message
- Replace
<CHAVE-JIRA>withEPIC-XXXX (Jira: falha na criacao) - Continue to Step 7 — NEVER block Epic file generation due to Jira failures
Step 7 — Save and Report
Save the file to ai/epics/epic-XXXX/epic-XXXX.md.
Report: number of rules extracted, number of stories identified, dependency structure summary.
<!-- TELEMETRY: phase.end -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-epic-create Phase-4-Epic-Generation ok
Step P4 — Commit Planning Artifacts (EPIC-0049 / RULE-007)
<!-- TELEMETRY: phase.start -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-epic-create Phase-P4-Planning-Commit
If --dry-run is set, log "dry-run, skipping commit" and skip this step entirely.
Otherwise, delegate the commit to x-commit-planning so the newly written ai/epics/epic-XXXX/epic-XXXX.md is versioned on the canonical epic/<ID> branch without triggering the code pre-commit chain (format / lint / compile):
Skill(skill: "x-commit-planning",
args: "--scope chore --epic-id <XXXX> --paths ai/epics/epic-<XXXX>/epic-<XXXX>.md --subject \"init epic specification\"")
Idempotency: re-executing the skill with identical inputs produces commitSha=null (silent no-op, RULE-007 --dry-run-like semantics on diff vazio). The contract is enforced by x-commit-planning itself — this step does not perform any additional diff check.
On COMMIT_FAILED (exit 4 from x-commit-planning), abort the workflow with the same error code so operators receive a single, unambiguous signal.
<!-- TELEMETRY: phase.end -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-epic-create Phase-P4-Planning-Commit ok
Step P5 — Push to Origin (optional, EPIC-0049)
<!-- TELEMETRY: phase.start -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh start x-epic-create Phase-P5-Push
If --dry-run is set, log "dry-run, skipping push" and skip.
When x-internal-ensure-epic-branch (Step P2) already pushed the branch to origin, the P4 commit is not yet on origin. Delegate the push to x-push-branch:
Skill(skill: "x-push-branch", args: "--branch epic/<XXXX>")
On push failure (remote rejection, no connectivity), log a WARNING and continue — the local commit is preserved; the operator can re-run Step P5 or git push manually. Do NOT abort.
<!-- TELEMETRY: phase.end -->
Bash command: $CLAUDE_PROJECT_DIR/.claude/hooks/telemetry-phase.sh end x-epic-create Phase-P5-Push ok
Error Handling
| Scenario | Action |
|---|---|
| Template file missing | Abort with message: "Template _TEMPLATE-EPIC.md not found" |
| Spec file missing or unparseable | Abort with message: "Specification file not found or invalid format" |
| Circular dependency in story graph | Warn, list the cycle, suggest merging conflicting stories |
| Story count too low (< 8 for complex spec) | Warn: "Possible over-bundling — review decomposition" |
| Jira MCP unavailable | Skip Jira integration silently, replace <CHAVE-JIRA> with — |
| Jira issue creation fails | Warn user, replace <CHAVE-JIRA> with failure message, continue |
x-internal-ensure-epic-branch fails (Step P2) |
Abort with EPIC_BRANCH_ENSURE_FAILED; canonical branch is required for versioning |
x-commit-planning exit 4 (Step P4) |
Abort with COMMIT_FAILED; file has already been written but not versioned |
x-commit-planning exit 0 + noOp=true (Step P4) |
Silent no-op — re-execution idempotency confirmed; continue to Step P5 |
x-push-branch fails (Step P5) |
WARN only; local commit preserved; operator re-runs manually |
--dry-run set |
Steps P4 and P5 become no-ops with log line "dry-run, skipping commit" / "dry-run, skipping push" |
Common Mistakes
- Missing rules: If a validation appears in 3+ journeys, it is cross-cutting — extract it
- Rules too vague: "Validar entidade" is useless. "Entidade deve estar ativa (status=ACTIVE) no cache L1/L2 -> DB. Se inativa, retornar 400 ENTITY_INACTIVE" is useful
- Dependency gaps: If Story B uses a table created by Story A, declare the dependency
- Circular dependencies: If A blocks B and B blocks A, they are probably one story
- Story count too low: A spec with 8 journeys typically generates 12-20 stories (infrastructure + journeys + cross-cutting). Fewer than 8 stories suggests over-bundling
Integration Notes
| Skill | Relationship | Context |
|---|---|---|
| x-epic-decompose | called-by | Orchestrator invokes x-epic-create in Phase B |
| x-story-create | calls | Story Creator reads the generated Epic file |
| x-epic-map | calls | Implementation Map reads the Epic's story index |
| x-create-jira-epic | calls | Creates Jira Epic from the generated file |
| x-manage-worktrees | calls (Step P1) | Detect-context (EPIC-0049 / RULE-001) |
| x-internal-ensure-epic-branch | calls (Step P2) | Ensure epic/<ID> exists locally + origin (EPIC-0049 / RULE-001) |
| x-commit-planning | calls (Step P4) | Batch-commit epic file without code pre-commit chain (EPIC-0049 / RULE-007) |
| x-push-branch | calls (Step P5) | Push canonical epic branch to origin (optional) |
| story-planning | reads | Reads decomposition guide for layer identification |
Knowledge Pack References
| Knowledge Pack | Usage |
|---|---|
| story-planning | Decomposition philosophy, layer identification, dependency validation |
Planning Status Propagation (Rule 22 / EPIC-0046)
V2-gated: only runs when the newly-created epic declares
planningSchemaVersion: "2.0"in its front matter / execution-state seed. For v1 epics (or epics with no version declaration): skip silently (Rule 19).
x-epic-create produces a fresh ai/epics/epic-XXXX/epic-XXXX.md from a spec. The epic's initial lifecycle status is Em Refinamento (per Rule 22 — an epic starts in refinement, not Pendente). There is NO transition at creation time; the skill simply writes **Status:** Em Refinamento in the generated artifact.
Steps (while materialising the epic file template):
-
Ensure the epic template contains the literal line:
**Status:** Em Refinamentoimmediately after the
**ID:**and**Chave Jira:**metadata block. -
After writing the epic file, validate the Status line is parseable by the CLI (sanity check, NOT a transition):
java -cp $CLAUDE_PROJECT_DIR/java/target/classes \ dev.iadev.adapter.inbound.cli.StatusFieldParserCli \ read ai/epics/epic-XXXX/epic-XXXX.mdExit code 0 required. Exit 20 → abort skill (epic template is malformed).
-
No separate commit is needed — the Status line is part of the initial epic file, committed with the rest of the epic creation.
Examples
# Default — v2 template (EPIC-0070 default)
Skill(skill: "x-internal-create-epic", args: "specs/my-spec.md")
# Explicit v2 (same as default, for documentation clarity)
Skill(skill: "x-internal-create-epic", args: "specs/my-spec.md --epic-id 0072")
# Legacy v1 template during deprecation window (Rule 19)
Skill(skill: "x-internal-create-epic", args: "specs/my-spec.md --legacy-template-v1")
# → Emits: WARN [legacy-template] --legacy-template-v1 is DEPRECATED...
# Dry-run: write file but skip commit + push
Skill(skill: "x-internal-create-epic", args: "specs/my-spec.md --dry-run")
# With Jira integration
Skill(skill: "x-internal-create-epic", args: "specs/my-spec.md --jira PROJ")
Fail-loud: validation read failure (exit 20) aborts the skill (RULE-046-08). Subsequent transitions out of Em Refinamento are owned by x-epic-decompose (to Pendente when decomposition completes) and x-implement-story/x-implement-epic (to Em Andamento, Concluída, etc.).
04 同仓库更多 Skills
x-parallel-eval
Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.
parallelism-heuristics
Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard / regen / soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.
x-watch-pr-ci
Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.
x-validate-docs
Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.
x-update-system-architecture
Incrementally updates docs/architecture/system.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.
x-update-architecture
Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.