Skill v1.0.2

name: smith-implement description: Execute the implementation plan by processing and executing all tasks defined in tasks.md metadata: version: "1.0.2"

Workflow requirement (Smith 20+): This skill must be invoked from inside an active top-level workflow (/smith-new, /smith-bugfix, /smith-debug, /smith-build). The workflow-gate hook will block standalone invocation. To use this skill standalone, start a top-level workflow first.

Vault Logging

Throughout this action, log significant events to the vault session log. Read the session log path from .smith/vault/.current-session. If the file is missing or the vault is not initialized, skip all logging silently.

Timestamps are UTC. HH:MM:SS comes from date -u +%H:%M:%S — never a local clock, never a time from memory. The append already runs through a shell, so read the clock in that same command (TS=$(date -u +%H:%M:%S)) and spend no extra tool call. Substitute the resulting value: an unexpanded $(...) reaching the log is a known regression and will not parse. Every hook-written stamp in this log is date -u, so a local-clock entry lands hours away from its neighbours and skews the workflow window hooks/workflow_summary_lib.py derives from them.

Append entries using this format:

### [HH:MM:SS] /smith-implement <event>
 
**User Request:**
> <verbatim user message that triggered this action>
 
**Synthesized Input:** <brief summary>
**Outcome:** <what happened>
**Artifacts:** <files created/modified>
**Systems affected:** <system IDs>

Log at these points:

1. On invocation — which tasks are being implemented (feature name, task count)
2. After each task — task title, status (success/failure), files modified
3. After tests — pass/fail summary
4. On completion — total tasks completed vs total tasks, any failures requiring attention

User Input

$ARGUMENTS

You MUST consider the user input before proceeding (if not empty).

Workflow Tracking

At the start of implementation, create a per-branch active-workflow file only if it doesn't already exist (it may already be set by /smith-new or /smith-build):

BRANCH=$(git rev-parse --abbrev-ref HEAD)
SAFE_BRANCH=$(echo "$BRANCH" | sed 's/[^a-zA-Z0-9._-]/-/g')
ACTIVE_FILE=".smith/vault/active-workflows/${SAFE_BRANCH}.yaml"
 
# Only create if not already set by parent workflow
if [ ! -f "$ACTIVE_FILE" ]; then
  mkdir -p .smith/vault/active-workflows
  cat > "$ACTIVE_FILE" << EOF
workflow: smith-implement
feature: <detected from branch or spec>
branch: $BRANCH
started: $(date -u +"%Y-%m-%dT%H:%M:%S")
EOF
fi

Clear the active-workflow file when all tasks are complete, only if smith-implement created it (not if inherited from parent). Use the shipped helper so this works on projects that deny Bash(rm:*):

# Only clean up if we created it (check workflow field)
if grep -q 'workflow: smith-implement' "$ACTIVE_FILE" 2>/dev/null; then
  .specify/scripts/bash/clear-active-workflow.sh "$BRANCH"
fi

If this action was invoked by /smith-build, the build action handles cleanup instead.

Outline

1. Run .specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot").

1. Check checklists status (if FEATURE_DIR/checklists/ exists):

• Scan all checklist files in the checklists/ directory
• For each checklist, count:
• Total items: All lines matching - [ ] or - [X] or - [x]
• Completed items: Lines matching - [X] or - [x]
• Incomplete items: Lines matching - [ ]
• Create a status table:

```text

```

• Calculate overall status:
• PASS: All checklists have 0 incomplete items
• FAIL: One or more checklists have incomplete items

• If any checklist is incomplete:
• Display the table with incomplete item counts
• STOP and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)"
• Wait for user response before continuing
• If user says "no" or "wait" or "stop", halt execution
• If user says "yes" or "proceed" or "continue", proceed to step 3

• If all checklists are complete:
• Display the table showing all checklists passed
• Automatically proceed to step 3

Ledger Context (Optional)

If .smith/vault/ledger/ exists and contains non-empty files, load relevant Ledger sections to inform implementation. If the directory is missing, empty, or unreadable, skip silently — the Ledger is purely additive and never required.

1. Check: ls .smith/vault/ledger/*.md 2>/dev/null
2. If files exist, read the following section (higher-confidence entries first, truncate at ~2000 tokens):

• .smith/vault/ledger/tool-preferences.md

1. Use loaded tool preferences as additional context when choosing implementation approaches. The Ledger informs judgment, it does not override spec/plan/constitution.
2. Budget violation tracking: If any Ledger file was truncated (entries were dropped to fit within the ~2000 token budget per file), increment context_budget_violations in .smith/vault/ledger/.meta.json by 1. If .meta.json does not exist, create it from the default template first. This signal tells the reconciliation system that the Ledger is too large for the configured budget.

1. Load and analyze the implementation context:

• REQUIRED: Read tasks.md for the complete task list and execution plan
• REQUIRED: Read plan.md for tech stack, architecture, and file structure
• IF EXISTS: Read data-model.md for entities and relationships
• IF EXISTS: Read contracts/ for API specifications and test requirements
• IF EXISTS: Read research.md for technical decisions and constraints
• IF EXISTS: Read quickstart.md for integration scenarios

1. Project Setup Verification:

• REQUIRED: Create/verify ignore files based on actual project setup:

Detection & Creation Logic:

• Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so):

``sh git rev-parse --git-dir 2>/dev/null ``

• Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore
• Check if .eslintrc* exists → create/verify .eslintignore
• Check if eslint.config.* exists → ensure the config's ignores entries cover required patterns
• Check if .prettierrc* exists → create/verify .prettierignore
• Check if .npmrc or package.json exists → create/verify .npmignore (if publishing)
• Check if terraform files (*.tf) exist → create/verify .terraformignore
• Check if .helmignore needed (helm charts present) → create/verify .helmignore

If ignore file already exists: Verify it contains essential patterns, append missing critical patterns only If ignore file missing: Create with full pattern set for detected technology

Common Patterns by Technology (from plan.md tech stack):

• Node.js/JavaScript/TypeScript: node_modules/, dist/, build/, *.log, .env*
• Python: __pycache__/, *.pyc, .venv/, venv/, dist/, *.egg-info/
• Java: target/, *.class, *.jar, .gradle/, build/
• C#/.NET: bin/, obj/, *.user, *.suo, packages/
• Go: *.exe, *.test, vendor/, *.out
• Ruby: .bundle/, log/, tmp/, *.gem, vendor/bundle/
• PHP: vendor/, *.log, *.cache, *.env
• Rust: target/, debug/, release/, *.rs.bk, *.rlib, *.prof*, .idea/, *.log, .env*
• Kotlin: build/, out/, .gradle/, .idea/, *.class, *.jar, *.iml, *.log, .env*
• C++: build/, bin/, obj/, out/, *.o, *.so, *.a, *.exe, *.dll, .idea/, *.log, .env*
• C: build/, bin/, obj/, out/, *.o, *.a, *.so, *.exe, Makefile, config.log, .idea/, *.log, .env*
• Swift: .build/, DerivedData/, *.swiftpm/, Packages/
• R: .Rproj.user/, .Rhistory, .RData, .Ruserdata, *.Rproj, packrat/, renv/
• Universal: .DS_Store, Thumbs.db, *.tmp, *.swp, .vscode/, .idea/

Tool-Specific Patterns:

• Docker: node_modules/, .git/, Dockerfile*, .dockerignore, *.log*, .env*, coverage/
• ESLint: node_modules/, dist/, build/, coverage/, *.min.js
• Prettier: node_modules/, dist/, build/, coverage/, package-lock.json, yarn.lock, pnpm-lock.yaml
• Terraform: .terraform/, *.tfstate*, *.tfvars, .terraform.lock.hcl
• Kubernetes/k8s: *.secret.yaml, secrets/, .kube/, kubeconfig*, *.key, *.crt

1. Parse tasks.md structure and extract:

• Task phases: Setup, Tests, Core, Integration, Polish
• Task dependencies: Sequential vs parallel execution rules
• Task details: ID, description, file paths, parallel markers [P]
• Execution flow: Order and dependency requirements

1. Execute implementation following the task plan:

• Phase-by-phase execution: Complete each phase before moving to the next
• Respect dependencies: Run sequential tasks in order, parallel tasks [P] can run together
• Follow TDD approach: Execute test tasks before their corresponding implementation tasks
• File-based coordination: Tasks affecting the same files must run sequentially
• Validation checkpoints: Verify each phase completion before proceeding

1. Implementation execution rules:

• Small, single-responsibility functions and files; one clear reason to

change. Keep files within the File Size Policy (300-line soft target, 500-line decomposition threshold) and honor the file structure plan.md prescribes — split large files rather than growing monolithic ones.

• Intention-revealing names (avoid data, temp, handler, util when a

meaningful name exists).

• Guard clauses over deep nesting; keep control flow shallow.
• Separation of concerns — keep I/O, business rules, and persistence in

distinct units.

• No dead code, commented-out blocks, or duplicated logic.
• Reuse existing components over recreating them — check for an existing

module/service/utility that already does it before writing something new.

• Setup first: Initialize project structure, dependencies, configuration
• Tests before code: If you need to write tests for contracts, entities, and integration scenarios
• Core development: Implement models, services, CLI commands, endpoints
• Integration work: Database connections, middleware, logging, external services
• Polish and validation: Unit tests, performance optimization, documentation

1. Progress tracking and error handling:

• Report progress after each completed task
• Halt execution if any non-parallel task fails
• For parallel tasks [P], continue with successful tasks, report failed ones
• Provide clear error messages with context for debugging
• Suggest next steps if implementation cannot proceed
• IMPORTANT For completed tasks, make sure to mark the task off as [X] in the tasks file.

1. Completion validation:

• Verify all required tasks are completed
• Check that implemented features match the original specification
• Validate that tests pass and coverage meets requirements
• Confirm the implementation follows the technical plan
• Report final status with summary of completed work

Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running /smith-tasks first to regenerate the task list.