Nacl Sa Full

NOT for /goal

This skill contains mandatory user confirmation gates at every phase boundary. Each gate requires the domain expert to verify graph writes before the next phase begins — Phase 2 (domain model per module), Phase 5 (UC detail per primary UC), and Phase 7 (validation) all produce graph output that must be reviewed for business correctness before proceeding. Autonomous execution would skip those reviews.

Refusal code: REFUSE_HUMAN_GATE_SA_PHASE_CONFIRMATION Background: docs/guides/goal-command.md

---

/nacl-sa-full --- Full SA Specification (Graph Orchestrator)

Purpose

Create a complete SA specification (technical spec / PRD) stored as a Neo4j graph through sequential invocation of 10 specialized graph skills. Each skill writes nodes and relationships to Neo4j --- no markdown files are produced (except at the optional publish phase). The result is a fully connected graph of modules, domain entities, roles, use cases, forms, requirements, and UI components, validated for internal consistency and ready for TL handoff.

The orchestration pattern is identical; only the storage backend changes (Neo4j graph instead of docs/ files).

---

Architecture

nacl-sa-full is an orchestrator that manages invocation of specialized graph SA agents in the correct order. It does NOT execute phases itself --- it delegates each phase to a dedicated skill via a Task agent (sub-agent with isolated context).

Key principle: facts come from the user, construction is done by the agent, confirmation is done by the user (same autonomy principle as sa-full).

---

Delegation Mechanism

Each phase is executed via a Task agent (sub-agent with separate context --- Tool: Task). This is critical: each phase generates substantial graph writes, and running them inline would exhaust L0 context by Phase 3-4.

Pattern for each phase:

1. L0 announces: "Starting Phase N: [name]..."
2. L0 launches: Launch Task agent: /nacl-sa-[skill] [mode]
3. Task agent does all work, writes to Neo4j, returns brief summary
4. L0 receives summary, updates progress tracker
5. L0 shows result to user and requests confirmation
6. User confirms -> L0 launches next Task agent

If a phase fails:

1. L0 shows the error message to the user
2. L0 asks: "Retry this phase, or skip and continue?"
3. If retry -> re-launch the same Task agent
4. If skip -> record as skipped in progress, move to next phase

L0 does only: queries graph for resume state, launches Task agents, shows gates, tracks progress. L0 does NOT: read source documents, generate graph data, run Cypher writes --- all of this is done by Task agents.

---

Workflow

+--------------+    +--------------+    +--------------+
| Phase 1      |    | Phase 2      |    | Phase 3      |
| nacl-sa-    |    | nacl-sa-    |    | nacl-sa-    |
| architect    |--->| domain       |--->| roles        |
| (modules,    |    | (per module) |    | (role model, |
|  Context Map,|    |              |    |  permissions)|
|  NFR)        |    |              |    |              |
+--------------+    +--------------+    +--------------+
                                               |
      +----------------------------------------+
      v
+--------------+    +--------------+    +--------------+
| Phase 4      |    | Phase 5      |    | Phase 6      |
| nacl-sa-    |    | nacl-sa-    |    | nacl-sa-    |
| uc stories   |--->| uc detail    |--->| ui           |
| (UC registry |    | (per Primary |    | (verify,     |
|  + stories)  |    |  UC, seq.)   |    |  components, |
|              |    |              |    |  navigation) |
+--------------+    +--------------+    +--------------+
                                               |
                                               v
                                        +--------------+
                                        | Phase 6b     |
                                        | connected-   |
                                        | spec ext.    |
                                        | (optional:   |
                                        |  screens ->  |
                                        |  slices ->   |
                                        |  errors ->   |
                                        |  resilience) |
                                        +--------------+
                                               |
      +----------------------------------------+
      v
+--------------+    +--------------+    +--------------+
| Phase 7      |    | Phase 8      |    | Phase 9      |
| nacl-sa-    |    | nacl-sa-    |    | nacl-publish|
| validate     |--->| finalize     |--->| docmost      |
| (L1-L13 +    |    | (statistics, |    | (optional)   |
|  XL6-XL9)   |    |  ADR,        |    |              |
|              |    |  readiness)  |    |              |
+--------------+    +--------------+    +--------------+
                                               |
      +----------------------------------------+
      v
+--------------+
| Phase 10     |
| nacl-tl-plan|
| (optional)   |
+--------------+

Each phase ends with user confirmation before proceeding to the next.

---

Neo4j Tools

| Tool | Purpose | |---|---| | mcp__neo4j__read-cypher | Read-only queries (resume detection, progress checks) | | mcp__neo4j__write-cypher | Not used by L0 directly --- all writes delegated to Task agents | | mcp__neo4j__get-schema | Schema introspection if needed |

Connection details are in nacl-core/SKILL.md.

---

Resume Detection

When starting, query the graph to detect which phases have already been completed. This allows resuming an interrupted orchestration without re-running completed phases.

// Phase 1: Module exists?
OPTIONAL MATCH (m:Module)
WITH count(m) > 0 AS phase1

// Phase 2: DomainEntity exists?
OPTIONAL MATCH (de:DomainEntity)
WITH phase1,
     count(de) > 0 AS phase2

// Phase 3: SystemRole exists?
OPTIONAL MATCH (sr:SystemRole)
WITH phase1, phase2,
     count(sr) > 0 AS phase3

// Phase 4: UseCase with user_story exists?
OPTIONAL MATCH (uc:UseCase)
WHERE uc.user_story IS NOT NULL
WITH phase1, phase2, phase3,
     count(uc) > 0 AS phase4

// Phase 5: UseCase with detail_status='complete' exists?
OPTIONAL MATCH (uc2:UseCase {detail_status: 'complete'})
WITH phase1, phase2, phase3, phase4,
     count(uc2) > 0 AS phase5

// Phase 6: Component exists?
OPTIONAL MATCH (c:Component)
WITH phase1, phase2, phase3, phase4, phase5,
     count(c) > 0 AS phase6

// Phase 6b: connected-spec extensions adopted? (optional phase, 2.15+)
OPTIONAL MATCH (ext)
WHERE ext:Screen OR ext:Slice OR ext:DomainError OR ext:CachePolicy OR ext:DegradationRule
WITH phase1, phase2, phase3, phase4, phase5, phase6,
     count(ext) > 0 AS phase6b

// Phase 7: SA ValidationReport exists?
OPTIONAL MATCH (vr:ValidationReport {layer: 'SA'})
WITH phase1, phase2, phase3, phase4, phase5, phase6, phase6b,
     count(vr) > 0 AS phase7

// Phase 8: SA FinalizationReport exists?
OPTIONAL MATCH (fr:FinalizationReport {layer: 'SA'})
WITH phase1, phase2, phase3, phase4, phase5, phase6, phase6b, phase7,
     count(fr) > 0 AS phase8

RETURN phase1, phase2, phase3, phase4, phase5, phase6, phase6b, phase7, phase8

Phase 6b is optional: phase6b = false with later phases true means the project declined the extension layers — do not treat it as "interrupted here". Only offer Phase 6b on resume when it is false AND Phase 7 has not run yet (or the user explicitly asks to adopt the layers).

Resume logic:

1. Run the resume detection query
2. Find the first phase where the result is false
3. Show the user the detected state:

``` Graph resume detection:

• Phase 1 (architect): DONE
• Phase 2 (domain): DONE
• Phase 3 (roles): DONE
• Phase 4 (uc stories): NOT STARTED (:DomainEntity) }

RETURN m.id, m.name ORDER BY m.id

Resume Phase 2 from the first module without domain entities.

**Phase 5 special case:** If Phase 5 is partially complete (some Primary UCs are detailed, others are not), detect which UCs still need detailing:

```cypher
MATCH (uc:UseCase {priority: 'MVP'})
WHERE uc.detail_status IS NULL OR uc.detail_status <> 'complete'
RETURN uc.id, uc.name
ORDER BY uc.id

Resume Phase 5 from the first Primary UC without detail_status='complete'.

---

Phase Details

Phase 1: Architecture -> /nacl-sa-architect full

Launch: Launch Task agent: /nacl-sa-architect full

What it does:

• Decomposes the system into modules (Bounded Contexts)
• Builds Context Map (inter-module relationships)
• Defines NFR (non-functional requirements)

Graph nodes created:

• Module (mod-NNN)
• Requirement (NFR-NNN) with type='NFR'
• Relationships: DEPENDS_ON (Module->Module), HAS_REQUIREMENT (Module->Requirement)

Transition: After user confirms module tree and Context Map -> Phase 2

---

Phase 2: Domain Model -> /nacl-sa-domain (per module)

Launch: For each module --- a separate Task agent (sequentially):

Launch Task agent: /nacl-sa-domain {module_id}

Wait for completion and user confirmation -> next module.

Discovery query:

MATCH (m:Module)
RETURN m.id, m.name
ORDER BY m.id

What it does (per module):

• Identifies domain entities within the module
• Defines attributes, types, constraints
• Establishes entity relationships (RELATES_TO)
• Creates enumerations and enum values

Graph nodes created (per module):

• DomainEntity (ent-NNN)
• DomainAttribute (attr-NNN)
• Enumeration (enum-NNN)
• EnumValue (ev-NNN)
• Relationships: CONTAINS_ENTITY, HAS_ATTRIBUTE, RELATES_TO, HAS_ENUM, HAS_VALUE

User prompt (after each module):

Domain model for {module_id} ({name}) created:
- {N} entities, {M} attributes
- {K} enumerations
- {J} inter-entity relationships

Confirm? (yes / adjust / skip)

Transition: After all modules complete -> Phase 3

---

Phase 3: Roles -> /nacl-sa-roles full

Launch: Launch Task agent: /nacl-sa-roles full

What it does:

• Defines system roles
• Maps business roles to system roles (if BA layer exists)
• Builds permission matrix (role -> entity CRUD)

Graph nodes created:

• SystemRole (role-NNN)
• Relationships: HAS_PERMISSION (SystemRole->DomainEntity with crud property), MAPPED_TO (BusinessRole->SystemRole, if BA exists)

Transition: After user confirms role model and permissions -> Phase 4

---

Phase 4: UC Stories -> /nacl-sa-uc stories

Launch: Launch Task agent: /nacl-sa-uc stories

What it does:

• Creates UC registry with User Stories and acceptance criteria
• Assigns priorities (MVP / Post-MVP / Nice-to-have)
• Links UCs to modules and actors

Graph nodes created:

• UseCase (UC-NNN) with userstory, acceptancecriteria, priority properties
• Relationships: CONTAINS_UC (Module->UseCase), ACTOR (UseCase->SystemRole)

Transition: After user confirms UC registry -> Phase 5

---

Phase 5: UC Detail -> /nacl-sa-uc detail UC-NNN (per Primary UC, sequential)

Launch: For each Primary UC (priority='MVP') --- a separate Task agent (sequentially, not in parallel --- each UC may modify the domain):

Launch Task agent: /nacl-sa-uc detail UC-{NNN}

Wait for completion and user confirmation -> next UC.

Discovery query:

MATCH (uc:UseCase {priority: 'MVP'})
WHERE uc.detail_status IS NULL OR uc.detail_status <> 'complete'
RETURN uc.id, uc.name
ORDER BY uc.id

What it does (per UC):

• Builds Activity Diagram (ActivityStep nodes)
• Designs forms (Form, FormField nodes)
• Maps form fields to domain attributes
• Defines functional requirements
• May add new DomainEntities/DomainAttributes discovered during detailing

Graph nodes created (per UC):

• ActivityStep (step-NNN)
• Form (form-NNN)
• FormField (field-NNN)
• Requirement (REQ-NNN) with type='functional'
• Relationships: HAS_STEP, USES_FORM, HAS_FIELD, MAPS_TO, HAS_REQUIREMENT, DEPENDS_ON

User prompt (after all Primary UCs):

UC detailing completed for Primary UCs:
- UC-{NNN}: {Name} (complete)
- UC-{NNN}: {Name} (complete)

Secondary UCs (not detailed):
- UC-{NNN}: {Name}
- UC-{NNN}: {Name}

Options:
1. Continue detailing Secondary UCs
2. Proceed to UI design (Phase 6)

Transition: After detailing at minimum all Primary UCs -> Phase 6

---

Phase 6: UI -> /nacl-sa-ui full

Launch: Launch Task agent: /nacl-sa-ui full

What it does:

• Verifies form-domain mapping completeness
• Creates shared UI components
• Builds navigation structure

Graph nodes created:

• Component (comp-NNN)
• Relationships: USED_IN (Component->Form)

Transition: After user confirms UI architecture -> Phase 6b

---

Phase 6b: Connected-spec Extensions (optional) -> /nacl-sa-ui state-machine + /nacl-sa-uc slices|errors|resilience

Goal: Adopt the 2.15+ extension layers — screen state machines (L10), behavior slices (L11), domain error taxonomy (L12), cache & degradation policies (L13) — while the SA context from Phases 5-6 is still fresh.

Gate (one for the whole phase): Offer adoption with a single confirmation. Default is adopt; opting out skips straight to Phase 7 and records extensions: skipped in progress — the L10-L13 vacuous pass in Phase 7 must be a documented choice, not an accident.

Launch order is hard (dependencies per docs/runbooks/upgrade-graph-extensions.md):

1. Screen machines — for every UC with coalesce(uc.has_ui, true) = true:

`` Launch Task agent: /nacl-sa-ui state-machine UC-{NNN} ``

Slices of UI UCs anchor via COVERS into ScreenState/Transition — machines must exist before slices.

1. Behavior slices — per UC (UI UCs after their machine; backend-only UCs

anchor via CALLS):

`` Launch Task agent: /nacl-sa-uc slices UC-{NNN} ``

1. Domain errors — per UC (module error catalogs are created here):

`` Launch Task agent: /nacl-sa-uc errors UC-{NNN} ``

Error-triggered degradation rules anchor via ON_ERROR into DomainError — errors must exist before resilience.

1. Resilience — per UC:

`` Launch Task agent: /nacl-sa-uc resilience UC-{NNN} ``

Each launch is a separate Task agent (same context-budget rule as the other phases). Steps run strictly in the order above; within a step, UCs run sequentially.

Verify-before-bulk: after the first UC of each step, run a scoped /nacl-sa-validate of the touched level (L10 after the first machine, L11 after the first slices run, L12 after errors, L13 after resilience) and show the user the result; 0 CRITICAL before queueing the remaining UCs.

Graph nodes created:

• Screen, ScreenState, ScreenEvent, Transition, ScreenEffect, AnalyticsEvent (SCR-, SCRST-, SCREV-, SCRTR-, SCREF-, ANEV-)
• Slice (SLC-NNN-*)
• DomainError, ErrorPresentation (ERR-, ERRP-)
• CachePolicy, DegradationRule (CACHE-, DEG-NNN-)

Transition: After all four steps (or an explicit skip) -> Phase 7

---

Phase 7: Validation -> /nacl-sa-validate full

Launch: Launch Task agent: /nacl-sa-validate full

What it does:

• SA internal consistency checks (L1-L13):
• L1: Data consistency (ids, names, types, duplicates)
• L2: Model connectivity (orphans, module assignment, floating attributes)
• L3: Requirement completeness (UCs have requirements, steps, actors)
• L4: Form-domain traceability (FormField MAPS_TO DomainAttribute)
• L5: UC-form validation (USES_FORM coverage, empty forms)
• L6: Cross-module consistency (shared entities, circular UC deps)
• L7: FeatureRequest consistency (FR nodes vs markdown, INCLUDES_UC)
• L8: Staleness closure (review_status on stale nodes)
• L9: Decision provenance (FR IMPLEMENTS Decision, rationale present)
• L10: Screen state machines (determinism, reachability, effect integrity)
• L11: Behavior slices (anchors, verificat

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: ITSalt
• Source: ITSalt/NaCl
• License: MIT

Install and usage instructions live in the source repository linked above.