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

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

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

Run the navigator in TOON format before manually selecting a workflow.
Inspect detected repository, branch, installed-skill count, discovered features, selected feature, workspace, stage, active skill, and dirty count.
Stop on an explicit-feature blocker; do not fall back to another feature.
Prefer the reported active or incomplete lifecycle action.
When no feature state exists, use intent routing and established-codebase signals to choose discovery, SDD, QA, review, security, or commit prep.
Confirm the required skill is installed; report a blocker when it is absent.
Present the required action first and optional actions separately.
Execute the downstream skill only when the user requested action; for an advisory request, return the report without mutation.
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.

ai-sdlc-navigator

NPX Install

Tags

SKILL.md Content

ai-sdlc-navigator: Context-Aware Workflow Navigation

0. Skill Card

0.1 Required Inputs

0.2 Clarification Rules

0.2.1 Flow Mode Flags

0.3 Output Rules

0.4 Artifact Routing

0.5 Feature State Machine

0.6 Artifact Metadata And Metatags

0.7 Specs Index

References

Script Usage

Purpose

Inputs

Steps

Output Spec

Examples

Edge Cases

Scope Boundary