Nacl Tl Next

/nacl-tl-next -- Graph-Aware Next Task Recommendation

Purpose

Graph-powered replacement for /nacl-tl-next. Queries Task and Wave nodes from Neo4j to recommend the optimal next task, enriched with UC entity names and form names from the SA layer. Falls back to .tl/status.json + master-plan.md when Neo4j is unavailable.

Critical difference from nacl-tl-next:

| Aspect | nacl-tl-next | nacl-tl-next | |--------|---------|---------------| | Data source | .tl/status.json + master-plan.md | Neo4j Task/Wave nodes (primary) | | Enrichment | Task title only | UC entity names, form names from SA layer | | Scoring | File-based computation | tl_task_scoring Cypher query | | Candidate list | Parsed from JSON | tl_actionable_tasks Cypher query | | Fallback | None | .tl/status.json + master-plan.md |

Shared references: nacl-core/SKILL.md

---

Your Role

• Query Neo4j for Task/Wave nodes, actionable candidates, and scoring
• Enrich recommendations with UC entity names, form names via tl_task_with_uc_context
• Identify the active wave via tl_active_wave query
• Analyze phase dependencies within each UC (BE -> review -> FE -> review -> sync -> stubs -> QA)
• Filter blocked tasks based on wave boundaries and cross-task dependencies
• Recommend a single action with phase-aware rationale and launch command
• Show parallel opportunities when multiple tasks are actionable
• Fall back to file-based mode if Neo4j is unreachable

Key Principle: Actionable Recommendation

CRITICAL: Always provide ONE clear recommendation with a launch command.

1. Single choice:    One task, not a list (unless --list flag)
2. Phase-aware:      Right phase for the UC lifecycle
3. Wave-aware:       Respect wave boundaries and parallelism
4. Unblocked:        No pending dependencies
5. Ready to start:   Immediate action command
6. Enriched:         UC entity/form context from SA layer

---

Neo4j Tools

| Tool | Usage | |------|-------| | mcp__neo4j__read-cypher | Read Task/Wave nodes, run scoring and actionable queries | | mcp__neo4j__get-schema | Verify TL layer exists in graph |

---

Invocation

/nacl-tl-next [flags]

Filtering Flags

/nacl-tl-next --be        # Only BE development tasks
/nacl-tl-next --fe        # Only FE development tasks
/nacl-tl-next --tech      # Only TECH tasks
/nacl-tl-next --review    # Only review tasks (BE or FE)
/nacl-tl-next --sync      # Only sync verification tasks
/nacl-tl-next --qa        # Only QA testing tasks
/nacl-tl-next --wave N    # Only tasks from wave N
/nacl-tl-next --list      # Show top 5 candidates with scores

---

Pre-Check Requirements

Before recommending, verify:

1. Neo4j reachable: Try mcp__neo4j__read-cypher with tl_active_wave query
2. TL layer exists: Task and Wave nodes present in graph
3. Tasks available: At least one actionable task exists

Decision: Graph or Fallback

Try Neo4j query (tl_active_wave)
  |
  +-- Success + results -> GRAPH MODE
  |
  +-- Connection error OR empty results -> FALLBACK MODE
      |
      +-- Check .tl/status.json exists
      |     +-- Yes -> file-based recommendation (same as nacl-tl-next)
      |     +-- No  -> error: "Project not initialized"

If falling back:

Note: Neo4j unavailable, using file-based fallback.
Recommendations based on .tl/status.json + master-plan.md.
Enrichment (entity/form names) unavailable in fallback mode.

Remote mode (multi-user shared graph): the FALLBACK path above is local mode only. When config.yaml graph.mode: remote (one shared graph, several developers), the .tl/status.json fallback is disabled — a per-clone cache cannot represent shared state. If Neo4j is unreachable, HALT with a clear message rather than recommend from stale local data. Additionally, in remote mode the recommendation is claim-first: first resolve the per-machine id with NACL_DEVELOPER_ID="$(node nacl-core/scripts/resolve-developer-id.mjs --project-root .)" (auto /, so one human on two machines never self-collides), then before presenting a task, claim it atomically with node nacl-core/scripts/claim-task.mjs claim --task --dev "$NACL_DEVELOPER_ID" (run the emitted Cypher via mcp__neo4j__write-cypher). If the returned owner ≠ you, another developer holds it — skip to the next candidate. See nacl-tl-core/references/remote-mode-coordination.md.

---

Workflow -- Graph Mode

Step 1: Determine Active Wave

Run tl_active_wave from graph-infra/queries/tl-queries.cypher:

// tl_active_wave
MATCH (t:Task)-[:IN_WAVE]->(w:Wave)
WHERE t.status <> 'done'
RETURN w.number AS active_wave, count(t) AS remaining_tasks
ORDER BY w.number
LIMIT 1

If no results: all tasks are complete -- show completion message.

Step 2: Get Actionable Tasks

Run tl_actionable_tasks from graph-infra/queries/tl-queries.cypher:

// tl_actionable_tasks
MATCH (t:Task)
WHERE t.status IN ['todo', 'pending']
AND NOT EXISTS {
  MATCH (t)-[:DEPENDS_ON]->(dep:Task) WHERE dep.status <> 'done'
}
OPTIONAL MATCH (t)-[:IN_WAVE]->(w:Wave)
RETURN t.id AS task_id, t.title AS title, t.status AS status,
       w.number AS wave, t.priority AS priority
ORDER BY w.number, t.priority

Apply filter flags to the result set:

• --be: keep only tasks where t.type = 'be'
• --fe: keep only tasks where t.type = 'fe'
• --tech: keep only tasks where t.type = 'tech'
• --review: keep only tasks where phase is *-review-pending
• --sync: keep only tasks where phase is sync-pending
• --qa: keep only tasks where phase is qa-pending
• --wave N: keep only tasks in wave N

Step 3: Score and Rank Candidates

Run tl_task_scoring from graph-infra/queries/tl-queries.cypher:

// tl_task_scoring
MATCH (t:Task)-[:IN_WAVE]->(w:Wave)
WHERE t.status IN ['todo', 'pending']
AND NOT EXISTS {
  MATCH (t)-[:DEPENDS_ON]->(dep:Task) WHERE dep.status <> 'done'
}
WITH t, w,
     CASE t.priority
       WHEN 'critical' THEN 40
       WHEN 'high' THEN 30
       WHEN 'medium' THEN 20
       WHEN 'low' THEN 10
       ELSE 15
     END AS priority_score,
     CASE WHEN w.number = 0 THEN 20 ELSE 10.0 / w.number END AS wave_score
OPTIONAL MATCH (other:Task)-[:DEPENDS_ON]->(t) WHERE other.status <> 'done'
WITH t, w, priority_score, wave_score,
     count(other) AS blocks_count
RETURN t.id AS task_id, t.title AS title, w.number AS wave,
       t.priority AS priority,
       priority_score + wave_score + (blocks_count * 5) AS total_score
ORDER BY total_score DESC
LIMIT 5

Then apply the full composite scoring formula on the client side using the Cypher result plus additional phase information:

score = priority_weight
      + status_order_weight
      + wave_bonus
      + dependency_bonus
      + phase_completion_bonus
      - age_penalty

| Component | Calculation | Description | |-----------|-------------|-------------| | priorityweight | critical=100, high=75, medium=50, low=25 | Task-level priority | | statusorderweight | QA=70, sync=60, review=50, stubs=45, fe=30, be=20, tech=10 | Phases closer to done score higher | | wavebonus | +20 if in current active wave | Prefer current wave | | dependencybonus | blockscount 10 | Tasks that unblock others | | phasecompletionbonus | +15 if UC has 4+ phases complete | Finish what is started | | agepenalty | min(dayssince_created 0.5, 10) | Slight preference for newer tasks |

Step 4: Enrich Top Candidate with SA Context

For the highest-scoring task, run tl_task_with_uc_context from graph-infra/queries/tl-queries.cypher:

// tl_task_with_uc_context($taskId)
MATCH (t:Task {id: $taskId})
OPTIONAL MATCH (uc:UseCase)-[:GENERATES]->(t)
OPTIONAL MATCH (uc)-[:USES_FORM]->(f:Form)
OPTIONAL MATCH (uc)-[:HAS_STEP]->(as_step:ActivityStep)
OPTIONAL MATCH (f)-[:HAS_FIELD]->(ff:FormField)-[:MAPS_TO]->(da:DomainAttribute)(w:Wave)
RETURN w.number AS wave,
       count(t) AS total,
       count(CASE WHEN t.status = 'done' THEN 1 END) AS done,
       count(CASE WHEN t.status = 'in_progress' THEN 1 END) AS in_progress,
       count(CASE WHEN t.status IN ['todo', 'pending'] THEN 1 END) AS pending,
       CASE WHEN count(t) > 0
         THEN round(100.0 * count(CASE WHEN t.status = 'done' THEN 1 END) / count(t))
         ELSE 0 END AS progress_pct
ORDER BY w.number

Step 6: Get Blocked Tasks for "Upcoming" Section

Run tl_blocked_tasks:

// tl_blocked_tasks
MATCH (t:Task)-[:DEPENDS_ON]->(dep:Task)
WHERE dep.status <> 'done'
RETURN t.id AS blocked_task, t.title AS blocked_title, t.status AS blocked_status,
       dep.id AS blocking_task, dep.title AS blocking_title, dep.status AS blocking_status

Step 7: Select and Present

Pick the single highest-scoring candidate. Present with full wave context, phase context, SA enrichment, parallel opportunities, and upcoming blockers.

---

Phase Action Priority Table

| Priority | Phase | Condition | Command | |----------|-------|-----------|---------| | 0 (highest) | delivery pending | every relevant Task is status: done AND last-fix Status: is in PASS-family (PASS or operator-accepted BLOCKED) | /nacl-tl-deliver or /nacl-tl-conductor | | 1 | QA pending | sync passed + stubs clean | /nacl-tl-qa UC### | | 2 | sync pending | BE approved + FE approved | /nacl-tl-sync UC### | | 3 | review-fe pending | FE dev complete | /nacl-tl-review UC### --fe | | 4 | review-be pending | BE dev complete | /nacl-tl-review UC### --be | | 5 | stubs pending | dev complete (any type) | /nacl-tl-stubs UC### | | 6 | fe pending | BE approved + api-contract exists | /nacl-tl-dev-fe UC### | | 7 | be pending | wave dependencies met | /nacl-tl-dev-be UC### | | 8 | tech pending | wave dependencies met | /nacl-tl-dev TECH### |

Priority 0 (/nacl-tl-deliver) recommendation rule

Recommend /nacl-tl-deliver ONLY when both conditions hold for every relevant Task:

1. Task.status == 'done', AND
2. The most recent fix/dev Status: line for that Task is PASS (or

BLOCKED with a recorded operator acceptance).

Do NOT recommend /nacl-tl-deliver as a normal next step when any relevant Task is in any of these states — instead, surface a prominent warning block:

• verification_status == 'verified-pending'
• Task.status == 'blocked'
• last-fix Status: is UNVERIFIED, NO_INFRA, RUNNER_BROKEN, or

REGRESSION

Warning block format:

[!! UNVERIFIED DELIVERY — NOT RECOMMENDED]

Task UC### has status `verified-pending` (or last fix Status: UNVERIFIED).

This task ships in unverified state — not recommended.

To unblock:
  - Run /nacl-tl-verify UC### or /nacl-tl-qa UC### to obtain PASS evidence, OR
  - Acknowledge unverified delivery via the explicit operator override on
    /nacl-tl-deliver itself (this skill will not recommend that path).

Suggested alternative next step: .

The warning block replaces the normal recommendation card; it does not appear alongside one. /nacl-tl-deliver is never silently recommended for unverified or blocked work.

---

Dependency Rules

TECH tasks (Wave 0):
  Must complete before Wave 1 tasks can start.

For each UC (within and across waves):
  BE dev -> BE review -> (api-contract must exist) -> FE dev
  FE dev -> FE review -> Sync check -> Stub scan -> QA test -> Done

Cross-UC:
  Tasks in the same wave can run in parallel.
  Tasks in later waves are blocked until previous wave completes.

Exception -- cross-wave phase unlock:
  If a UC's BE is approved and api-contract exists, the FE task
  for that UC CAN start even if it belongs to a later wave.
  Shown in "Also ready" section, not as primary recommendation.

---

UC Lifecycle Phases

Each UC goes through these phases in strict order:

Phase 1: BE Development     -> nacl-tl-dev-be UC###
Phase 2: BE Review          -> nacl-tl-review UC### --be
Phase 3: FE Development     -> nacl-tl-dev-fe UC### (requires BE approved + api-contract)
Phase 4: FE Review          -> nacl-tl-review UC### --fe
Phase 5: Sync Verification  -> nacl-tl-sync UC###   (requires BE + FE approved)
Phase 6: Stub Scan          -> nacl-tl-stubs UC###  (requires sync passed)
Phase 7: QA Testing         -> nacl-tl-qa UC###     (requires stubs clean)
Phase 8: Done

TECH Task Lifecycle

Phase 1: Development        -> nacl-tl-dev TECH###
Phase 2: Review             -> nacl-tl-review TECH### --be  (TECH reviewed as BE)
Phase 3: Done

---

Output Format

Standard Recommendation (Graph Mode)

===============================================================
                         NEXT TASK
===============================================================

  UC003: Delete Order -- Backend Development

Wave:        2 (Core Frontend + Next BE)
Phase:       BE Development
Priority:    high
Estimated:   2 hours

Entities:    Order, OrderItem, AuditLog
Forms:       DeleteConfirmationDialog
Steps:       6 activity steps

Description:
Implement backend API for order deletion with soft-delete
pattern and cascade handling.

Why this task:
  * Highest priority pending task in current wave
  * Unblocks UC003-FE in Wave 3
  * No dependencies (UC001-BE, UC002-BE already done)
  * Touches 3 domain entities (Order, OrderItem, AuditLog)

---------------------------------------------------------------

  Start now:
   /nacl-tl-dev-be UC003

---------------------------------------------------------------

Also ready (can run in parallel):
  * UC001-FE: Frontend development (/nacl-tl-dev-fe UC001)
    Wave 2, FE phase, BE already approved
    Forms: OrderForm, OrderListFilter

Upcoming (blocked):
  * UC002-FE: Waiting for current wave
  * UC001-SYNC: Waiting for UC001-FE completion

Wave Progress:
  Wave 0: [done]     100%  All TECH tasks done
  Wave 1: [done]     100%  All tasks done
  Wave 2: [active]    33%  2 of 6 done
  Wave 3: [blocked]    0%  Waiting for Wave 2

Source: Neo4j graph (Task/Wave nodes)
===============================================================

Enriched Sync Verification Ready

===============================================================
                         NEXT TASK
===============================================================

  UC001: Create Order -- Sync Verification

Both BE and FE are approved. Run sync check to verify
API contract compliance before QA.

Wave:      2       Phase:     Sync
Priority:  high    Reason:    Unblocks QA for UC001

Entities:  Order, Customer, OrderItem
Forms:     OrderForm (12 fields), CustomerSelect (3 fields)

  Start now: /nacl-tl-sync UC001

Source: Neo4j graph
===============================================================

Enriched QA Testing Ready

===============================================================
                         NEXT TASK
===============================================================

  UC001: Create Order -- QA Testing

All phases complete. Run E2E testing via Playwright.

Wave:      2       Phase:     QA
Priority:  critical (final validation)

Entities:  Order, Customer, OrderItem
Forms:     OrderForm, CustomerSelect
Steps:     8 activity steps (test scenarios)

  Start now: /nacl-tl-qa UC001

Source: Neo4j graph
===============================================================

List Mode (--list)

===============================================================
               TOP 5 TASK CANDIDATES
===============================================================

  Active Wave: 2
  Source: Neo4j graph (tl_task_scoring)

#  Score  Task                      Phase        Entities        Command
-- ------ ------------------------- ------------ --------------- ----------------------
1  135    UC003-BE Delete Order     BE Dev       Order,AuditLog  /nacl-tl-dev-be UC003
2  125    UC001-FE Create Order     FE Dev       Order,Customer  /nacl-tl-dev-fe UC001
3  110    UC002-FE Edit Order       FE Dev       Order,OrderItem /n

…

## Source & license

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

- **Author:** [ITSalt](https://github.com/ITSalt)
- **Source:** [ITSalt/NaCl](https://github.com/ITSalt/NaCl)
- **License:** MIT

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