--- name: ai-sdlc-navigator description: AI SDLC context-aware navigation workflow. Use when an AI assistant needs to determine what to do next, select the right installed skill, start or resume a feature, explain blockers, inspect available capabilities, or provide evidence-backed required and optional next actions from repository state. Supports `--quick-flow` for compact guidance and `--full-flow` for stricter context verification. --- # ai-sdlc-navigator: Context-Aware Workflow Navigation > Internal AI SDLC skill, not client-facing by default. > Every rule below is important to follow. None of it can be skipped. > Before producing the final recommendation, confirm the target repository, > explicit feature, user intent, and requested output format when they are > unclear. > Do not invent missing feature state or installed capabilities. ## 0. Skill Card - Skill name: `ai-sdlc-navigator` - Primary audience: PM, BA, QA, Delivery, Dev - Supporting audience: AI assistants, agent runners, workflow maintainers - Audience tags: PM, BA, QA, Delivery, Dev - SDLC stage: Cross-lifecycle navigation - Purpose: Inspect compact repository control records and recommend one ranked required action plus relevant optional actions with reasons, exact invocations, expected artifacts, and blockers. - Output: Read-only Markdown or TOON navigation report ### 0.1 Required Inputs - Target repository root. - Optional natural-language intent. - Optional explicit feature slug. - Requested human-readable Markdown or compact TOON format. ### 0.2 Clarification Rules - Ask a concise question only when the repository or explicitly requested feature cannot be identified safely. - Treat an omitted feature as optional; resolve it from active state, current branch, and recent state records. - Separate detected evidence from routing inference. - Report corrupt, missing, blocked, or unavailable context instead of silently selecting a different feature. ### 0.2.1 Flow Mode Flags - Support `--quick-flow` and `--full-flow`; full flow takes precedence when both are supplied. - In quick flow, use compact state, branch, installed-skill, and intent signals and avoid broad repository reads. - In full flow, verify the explicit feature state, selected skill availability, workspace indexes, and reported blockers before recommending handoff. - Neither mode may mutate lifecycle state or artifacts. - When neither flag is supplied, perform deterministic default navigation. ### 0.3 Output Rules - Lead with the detected feature and next required action. - Always include detected context, `next_required`, `next_optional`, and blockers. - For every action include exact skill name, evidence-backed reason, portable invocation guidance, and expected artifact. - Return the navigation report directly in the Codex response. - Return progress, blockers, and recommendations directly in the Codex response. - Before the final response, emit the `ai-sdlc-handoff/v1` contract with `result`, `blockers`, `next_required`, and `next_optional`; every action includes `reason`, `command`, and `expected_artifact`. - Do not create `summary.txt`, `*-summary.txt`, or a durable navigation artifact. - Do not imply that an optional action is a lifecycle predecessor. ### 0.4 Artifact Routing - This skill is read-only and produces no canonical artifact. - Read refinement control records from `specs-refiniment/` and implementation control records from `specs/`. - Do not create or update decision logs, SDD artifacts, refinement artifacts, indexes, or plans. - Route durable work to the recommended downstream skill. ## 0.5 Feature State Machine - The navigator is a utility and is not a lifecycle transition. - Read canonical `specs-refiniment//_ai_sdlc/state.toon` or `specs//_ai_sdlc/state.toon` before broad artifacts. - Prefer an explicit feature, then an active skill, then a feature matching the current branch, then the most recently updated state. - When a feature has an active skill, recommend resuming it before intent-based routing. - When no skill is active, recommend the first incomplete stage in the selected workspace. - Never call `begin` or `complete` from this skill. ## 0.6 Artifact Metadata And Metatags - Navigation output is ephemeral and does not carry `artifact_metadata`. - Navigation output does not create or update artifact `metatags`. - Use artifact metadata only as read-only routing evidence when a downstream decision needs artifact status, flow mode, owner, or trace IDs. - Do not treat metadata as a replacement for state or visible artifact content. ## 0.7 Specs Index - Inspect `specs-refiniment/_ai_sdlc/specs-index.toon` and `specs/_ai_sdlc/specs-index.toon` before broad feature searches when they exist. - Use `specs-refiniment/specs-index.md` and `specs/specs-index.md` only when a human-readable inventory is needed. - Use feature-local `state.toon` as lifecycle authority. - Report a stale or missing index as a blocker only when it prevents safe feature selection in full flow. - Do not rebuild indexes from this skill. ## References - Use `scripts/navigate.py` for deterministic repository inspection, feature selection, and Markdown or TOON rendering. - Read `references/routing-contract.md` only when changing signal precedence, required output fields, or navigation safety behavior. ## Script Usage - Default Markdown guidance: ```bash python3 skills/ai-sdlc-navigator/scripts/navigate.py \ --intent "" --format markdown ``` - Compact agent routing: ```bash python3 skills/ai-sdlc-navigator/scripts/navigate.py \ --feature --intent "" \ --quick-flow --format toon ``` - Strict feature verification: ```bash python3 skills/ai-sdlc-navigator/scripts/navigate.py \ --feature --full-flow --format toon ``` - A non-zero exit means one or more reported blockers remain; do not discard the report. ## Purpose Give users and AI assistants one reliable entry point into the AI SDLC harness without requiring them to memorize installed skills, lifecycle order, feature state, or artifact paths. ## Inputs - Collect the repository root from the current workspace or `--root`. - Collect the user request as `--intent` when intent should influence fallback routing. - Collect `--feature` when the user identifies an exact feature. - Collect current branch, dirty-tree count, installed skill directories, and feature-local state through the script. - In full flow, confirm relevant workspace indexes exist when features are expected. ## Steps 1. Run the navigator in TOON format before manually selecting a workflow. 2. Inspect detected repository, branch, installed-skill count, discovered features, selected feature, workspace, stage, active skill, and dirty count. 3. Stop on an explicit-feature blocker; do not fall back to another feature. 4. Prefer the reported active or incomplete lifecycle action. 5. When no feature state exists, use intent routing and established-codebase signals to choose discovery, SDD, QA, review, security, or commit prep. 6. Confirm the required skill is installed; report a blocker when it is absent. 7. Present the required action first and optional actions separately. 8. Execute the downstream skill only when the user requested action; for an advisory request, return the report without mutation. 9. Rerun navigation after durable downstream completion when the next phase is still unclear. ## Output Spec Markdown output must contain: ```text Detected Context: - repository, branch, installed skills, features, selected feature, workspace, current stage, active skill, dirty count, flow mode Next Required: - skill, reason, command, expected artifact Next Optional: - zero or more actions with the same fields Blockers: - none or explicit blocker messages ``` TOON output uses schema `ai-sdlc-navigator/v1` and arrays: `next_required[1]`, `next_optional[N]`, and `blockers[N]`. Quality gate: - Pass when the selected feature follows signal precedence, the required skill is installed, every action contains all contract fields, and blockers are explicit. - Fail when the navigator silently changes an explicit feature, recommends a missing skill without a blocker, mutates repository state, or mixes optional actions with required predecessors. ## Examples Valid resume request: ```text User: What should I do next for 101-payment-retry? Navigator: ai-sdlc-validation is required because branching is complete and validation is the first incomplete implementation stage. ``` Valid empty-project request: ```text User: I have a product idea. Where do I start? Navigator: ai-sdlc-working-backwards-discovery is required because no active feature state or established codebase signal exists. ``` Invalid counter-example: ```text The requested feature was not found, so I selected another recent feature. ``` Reject this because explicit feature identity is authoritative. ## Edge Cases - When refinement and implementation state exist for the same explicit feature, prefer implementation only when no state has an active skill. - When multiple features have active skills, select deterministically and make the ambiguity visible in blockers during full flow. - When Git is unavailable, report `not-a-git-repository` and continue with repository-local state. - When state parsing fails, skip the corrupt record in quick flow and report it as a blocker in full flow. - When no recommended skill is installed, retain the recommendation and add an installation blocker. - Treat dirty-tree count as context, not automatic authorization to edit or clean files. ## Scope Boundary - Do not perform the recommended workflow; invoke the downstream skill. - Do not create, repair, or complete lifecycle state. - Do not generate delivery artifacts, code, tests, reviews, or commits. - Do not choose validation commands; use `$ai-sdlc-validation`. - Do not resolve product or technical decisions; route to the owning skill and decision log.