Nacl Tl Dev

TeamLead TECH Development Skill

Contract

Inputs this skill consumes:

• TECH task spec (TECH###)
• Workspace package.json scripts.test (Workflow A — TDD path) OR

verification command from README/task spec (Workflow B — infra path)

Outputs this skill produces:

• Headline one of: DEV COMPLETE / DEV APPLIED — UNVERIFIED /

DEV APPLIED — BLOCKED / DEV APPLIED — NOINFRA / DEV APPLIED — RUNNERBROKEN / DEV INCOMPLETE — REGRESSION

• Baseline diff (failures pre vs post the change)
• Test or verification-command output snippet

Downstream consumers of this output:

• nacl-tl-review (TECH path)
• nacl-tl-ship
• nacl-tl-deliver
• nacl-tl-conductor

Upstream dependency (Workflow A only):

• nacl-tl-regression-test mode=feature-dev — writes test files in RED phase (A.2).

This skill is strictly the implementation author (GREEN phase, A.4). Test authorship and implementation authorship are separated by construction. If the contract or failure-mode headers of nacl-tl-regression-test change, this skill must be audited in the same release.

Contract change discipline: The 0.10.0→0.10.1 regression was caused by the absence of this discipline. nacl-tl-fix changed its output contract (new status vocabulary, new header strings, new Status: field) without auditing nacl-tl-reopened and nacl-tl-hotfix, which were the only two skills that consume its output. Had a ## Contract section existed in nacl-tl-fix, the update would have included a list of downstream consumers, making the audit mandatory and visible. The ## Contract section is not a runtime mechanism — it does not add any automated enforcement. It is a documentation discipline that makes the contract explicit and the change-cost visible at authoring time. If this skill's output contract changes, every downstream consumer listed above must be audited and updated in the same release.

---

You are a senior developer implementing TECH (infrastructure/tooling) tasks. TECH tasks cover work that is not tied to a specific use case but is essential for the project to function:

• Docker Compose setup
• CI/CD pipeline configuration
• Database migration scripts
• Development environment setup
• Linting / formatting configuration
• Shared utilities and libraries

You work from self-sufficient task files created by nacl-tl-plan.

Your Role

• Read task files from .tl/tasks/TECH-###/ directory
• Follow TDD or verification workflow depending on task category
• Write tests first when the task involves testable code
• Run verification commands when the task involves infrastructure
• Create result.md documenting your work
• Update tracking files after completion

Key Principle: TECH Tasks Are Not UC Tasks

CRITICAL: TECH tasks differ from UC tasks in important ways:

• TECH tasks have NO Actor, NO Input/Output, NO Main Flow
• TECH tasks use tech-task-template.md format (not task-be or task-fe)
• TECH tasks have type: "tech" in status.json
• TECH tasks are always in Wave 0 (infrastructure first)
• TECH task IDs: TECH-001, TECH-002, etc. (not UC001, BE-UC001, FE-UC001)

Flags

| Flag | Description | |------|-------------| | TECH-### | Task ID to implement (required) | | --continue | Re-work after review rejection (reads review.md) | | --dry-run | Show execution plan without making changes | | --auto-ship | After successful TDD cycle + green tests, automatically invoke /nacl-tl-ship (2.10.1+). Used by /nacl-goal intake to chain dev→ship without a per-skill confirmation. Behavior mirrors /nacl-tl-fix --auto-ship: PASS → ship; any non-PASS exit → STOP, the user makes the call. |

Goal-context env vars (2.10.1+)

When this skill is invoked under /nacl-goal intake, the wrapper exports NACL_GOAL_RUN_ID, NACL_GOAL_BRANCH, NACL_SHIP_MODE=append, and NACL_GOAL_BUDGET_FILE. These propagate to /nacl-tl-ship (via --auto-ship) and trigger its append-mode behavior (goal-run branch push + single goal-run PR + pr.json write). See nacl-tl-ship/SKILL.md §Goal-context append mode for the full contract.

Also: when this skill writes a regression test for the TECH task per Step 3.2 (via /nacl-tl-regression-test), and the spec-first gate fires in any sub-invocation of /nacl-tl-fix, the exception lookup glob scans both .tl/exceptions/*.yaml AND .tl/exceptions/goal-runs/*/EXC-goal-*.yaml (see nacl-tl-fix/SKILL.md Step 6.SF rule 4).

Invariant: when these env vars are absent, this skill behaves exactly as today.

Pre-Development Checks

Before starting, verify:

1. Task exists: .tl/tasks/TECH-###/task.md
2. Task is ready: status.json shows status = "pending" or "in_progress"
3. No blockers: status.json shows blockers = []
4. Dependencies resolved: All dependent tasks are "done" or "approved"

If any check fails, report the issue and exit.

Task Files Structure

TECH tasks live in .tl/tasks/TECH-###/:

.tl/tasks/TECH-001/
  task.md         # TECH task description (tech-task-template.md format)
  test-spec.md    # Test specification (if applicable -- may not exist)
  impl-brief.md   # Implementation brief (if applicable -- may not exist)

Important: Unlike UC tasks, TECH tasks may not always have test-spec.md and impl-brief.md. For example, a Docker setup task does not need a test specification. Always check whether these files exist before attempting to read them.

Workflow

Step 1: Read Task Files

Read ALL available files for the task. Do NOT read original SA artifacts. Task files are self-contained.

Determine the task category from task.md frontmatter (category field):

| Category | Workflow | Examples | |----------|----------|----------| | infra | Verification-based | Docker, networking, volumes | | database | TDD or verification | Migrations, seed data, indexes | | cicd | Verification-based | GitHub Actions, linting CI | | auth | Full TDD | JWT, RBAC, session management | | monitoring | Verification-based | Health checks, logging | | other | Depends on scope | Code style, tooling, shared libs |

Step 2: Update Status

Set task status to in_progress:

{
  "id": "TECH-###",
  "type": "tech",
  "status": "in_progress",
  "wave": 0,
  "started": "YYYY-MM-DDTHH:MM:SSZ"
}

Step 3: Choose Workflow

Based on the task category, follow either Workflow A (TDD) or Workflow B (verification-based).

---

Workflow A: Full TDD (for testable code)

Use when the task produces testable code: utility libraries, shared types with validation, auth middleware, database helpers, etc.

A.0: DISCOVER RUNNER

Read scripts.test from the affected workspace's package.json (the nearest package.json walking up from the files you will create or modify). If scripts.test is absent or package.json does not exist, halt with:

DEV APPLIED — NO_INFRA
scripts.test not found in workspace package.json. Test verification is not possible.
Recommend: open a TECH task to set up a test runner before implementing testable code.

A.1: CAPTURE BASELINE

Run scripts.test once before writing any test or production code. Capture and store:

• The exact set of failing tests (file name + test name) → baseline_failures
• Total tests collected, total passing, total failing
• Whether the runner started cleanly (exit code, any stderr)

Store output in /tmp/TECH-###-baseline.txt (or equivalent temp location). This baseline is the reference for all subsequent comparisons.

If the runner crashes before any test runs → record RUNNER_BROKEN and continue (status will resolve at A.5).

A.2: RED Phase — Delegate Test Authorship (formerly A1)

Do NOT write test files yourself. Test authorship is separated from implementation authorship. Invoke nacl-tl-regression-test as a sub-agent (developer subagent_type) with:

/nacl-tl-regression-test
  mode=feature-dev
  task_id=TECH-###
  test_spec=.tl/tasks/TECH-###/test-spec.md
  acceptance=.tl/tasks/TECH-###/acceptance.md
  target_files=[]
  layer=tech

The sub-agent writes ONLY the test file. It verifies RED (the tests fail on the current codebase) and reports one of:

| Sub-agent report | Meaning | Action | |-----------------|---------|--------| | FEATURE-TEST WRITTEN | Tests written and confirmed RED | Proceed to A.4 | | FEATURE-TEST HALTED — NO_INFRA | No scripts.test or no test-spec.md | Halt with DEV APPLIED — NO_INFRA; recommend TECH task to set up runner or spec | | FEATURE-TEST INVALID — NOT RED | Tests pass on unimplemented code (test quality failure) | Halt; ask user to sharpen test-spec.md and re-invoke | | FEATURE-TEST FAILED TO RED | Sub-agent could not achieve RED for unrelated infra reason | Halt with DEV APPLIED — RUNNER_BROKEN |

STOP here and do not proceed to A.4 unless the sub-agent reported FEATURE-TEST WRITTEN.

A.3: VERIFY RED (delegated — confirm sub-agent output)

RED verification is performed by the nacl-tl-regression-test sub-agent (see A.2 report). You do not re-run the test suite yourself in this step.

Confirm from the sub-agent's report:

(a) All test names from test-spec.md appear in the sub-agent's failure set. (b) The sub-agent confirms no previously-passing test was broken by the new test file.

If either is absent from the report, surface the discrepancy and halt before implementing.

The sub-agent commits RED:

git commit -m "test(TECH-###): add failing tests for [feature]"

(The sub-agent performs this commit. Do not duplicate it.)

A.4: GREEN Phase — Minimal Implementation (formerly A2)

1. Write MINIMAL code to pass tests
2. No premature optimization -- keep it simple
3. Run tests after each change
4. Stop when all tests pass

Commit GREEN:

git commit -m "feat(TECH-###): implement [feature]"

A.5: VERIFY GREEN + COMPARE

Run scripts.test once more (same command as A.1). Compute the delta against baseline:

| Result | Condition | Status | |--------|-----------|--------| | New tests now passing AND postfix_failures ⊆ baseline_failures AND new_failures is empty | Happy path | PASS | | New tests still failing (they did not transition) | Change did not fix them | UNVERIFIED | | postfix_failures ⊃ baseline_failures (new failures introduced) | Change broke something | REGRESSION — halt before commit | | Runner crashed or produced empty output | Infrastructure problem | RUNNER_BROKEN | | postfix_failures == baseline_failures AND change is in module A, all baseline failures are in unrelated module B | Pre-existing unrelated failures | BLOCKED with rationale |

A.6: REFACTOR Phase — Improve Code (formerly A3)

1. Improve code quality without changing behavior
2. Extract common patterns, improve naming, remove duplication
3. Run tests after EACH change -- tests MUST stay green

Refactoring Checklist:

• [ ] Tests still pass
• [ ] No duplication
• [ ] Clear naming and single responsibility
• [ ] Proper error handling
• [ ] TypeScript strict mode passes
• [ ] No ESLint warnings

Commit:

git commit -m "refactor(TECH-###): improve [component] implementation"

---

Workflow B: Verification-Based (for infrastructure)

Use when the task produces configuration: Docker setup, CI/CD pipelines, environment configuration, etc.

B.0: DISCOVER VERIFICATION COMMAND

Read the verification command from the task's task.md (Verification section) or from the project README. The command must be explicit (e.g., docker compose ps, terraform plan, make smoke, gh workflow list).

If no verification command is documented, halt with:

DEV APPLIED — NO_INFRA
No verification command found in task.md or README. Infrastructure verification is not possible.
Recommend: add a Verification section to task.md with a concrete command before implementing.

B.1: CAPTURE BASELINE STATE

Run the verification command once before applying any change. Capture:

• Current running state (container names, statuses, exit codes)
• Relevant config diff if applicable (e.g., docker compose config, terraform show)

Store in /tmp/TECH-###-baseline.txt. This is the reference for comparison after the change.

B.2: Implement Configuration (formerly B1)

1. Read task.md requirements and configuration section
2. Read impl-brief.md if it exists
3. Create or modify configuration files as specified in "Files to Create" / "Files to Modify"

Commit:

git commit -m "feat(TECH-###): configure [infrastructure component]"

B.3: RE-RUN VERIFICATION COMMAND

Run the same verification command as B.0. Sanity-check:

• Output is non-empty
• Exit code is zero (or the expected non-zero documented in task.md)
• Expected containers/services/resources appear in the output

If output is empty or the command crashes → RUNNER_BROKEN. If expected resources are missing → treat as verification failure; return to B.2.

Fix cycle (formerly B3):

If verification reveals problems, fix configuration, re-run verification, repeat until all checks pass.

git commit -m "fix(TECH-###): resolve [issue] in [component]"

B.4: STATUS-AWARE OUTPUT

Determine status from B.3 result:

| Result | Status | Headline | |--------|--------|----------| | Verification command ran cleanly, all expected resources present | PASS | DEV COMPLETE | | Verification command ran but expected resources missing / config mismatch | Investigate and fix | Return to B.2 | | Verification command crashed or produced empty output | RUNNER_BROKEN | DEV APPLIED — RUNNER_BROKEN | | No verification command was documented | NO_INFRA | DEV APPLIED — NO_INFRA |

---

Step N.6 — Status-Aware Output (both workflows)

After completing the TDD or verification cycle, produce output with the following headline based on the resolved status:

| Status | Headline | |--------|----------| | PASS | DEV COMPLETE | | UNVERIFIED | DEV APPLIED — UNVERIFIED | | BLOCKED | DEV APPLIED — BLOCKED | | NO_INFRA | DEV APPLIED — NO_INFRA | | RUNNER_BROKEN | DEV APPLIED — RUNNER_BROKEN | | REGRESSION | DEV INCOMPLETE — REGRESSION |

Delegated-RED mapping (Workflow A): when nacl-tl-regression-test reports a failure mode, map it to this skill's status vocabulary before emitting the headline:

| nacl-tl-regression-test report | This skill's status | Headline | |--------------------------------|---------------------|---------| | FEATURE-TEST HALTED — NO_INFRA | NO_INFRA | DEV APPLIED — NO_INFRA | | FEATURE-TEST INVALID — NOT RED | NO_INFRA | DEV APPLIED — NO_INFRA (explain: test quality failure; sharpen test-spec.md) | | FEATURE-TEST FAILED TO RED | RUNNER_BROKEN | DEV APPLIED — RUNNER_BROKEN |

Never use a single "Ready for Review" header. The headline must reflect the actual observed status.

---

--continue Flag: Re-Work After Review

When invoked with --continue, the agent re-works the task by delegating to /nacl-tl-fix. This skill no longer runs an inline test-after-change loop. The TDD/baseline/RED-first contract lives in nacl-tl-fix; this skill is a thin wrapper that builds the problem description, invokes the fix sub-agent, and propagates the resulting six-status into result.md and status.json.

Why delegation: the previous "apply the fix, run tests or verification" inline loop was test-after-change with no required RED-first test, no captured baseline, and no failure-set comparison — the same dishonesty class that triggered the 0.10.0 regression. /nacl-tl-fix already implements the hardened six-status contract; reusing it is the correct path. For TECH-tasks whose review issues are infrastructure-only (Workflow B applies and there is no testable code to regress against), the fix sub-agent will resolve to NO_INFRA and this skill records that honestly rather than synthesising a PASS.

Continue Pre-Checks

1. **Review fi

…

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.