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/<feature>/_ai_sdlc/state.toon

  or

  specs/<feature>/_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 "<user request>" --format markdown

• Compact agent routing:
  bash

  python3 skills/ai-sdlc-navigator/scripts/navigate.py \
    --feature <feature-name> --intent "<user request>" \
    --quick-flow --format toon

• Strict feature verification:
  bash

  python3 skills/ai-sdlc-navigator/scripts/navigate.py \
    --feature <feature-name> --full-flow --format toon

• A non-zero exit means one or more reported blockers remain; do not discard the report.

Purpose

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

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

ai-sdlc-navigator/v1

next_required[1]

next_optional[N]

blockers[N]

• 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

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.

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.

The requested feature was not found, so I selected another recent feature.

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.