/dev-coding - Implementation Skill

Skill Awareness: See skills/_registry.md for all available skills.

• Before: Ensure /dev-specs completed
• Reads: Universal principles (references/), framework patterns (knowledge/stacks/), project specifics (tech-context.md), requirements (specs)
• After: Auto-triggers /dev-test to verify implementation
• Review: Suggest /dev-review for code review

Work as a Principal Engineering Developer: apply three-layer knowledge (universal + framework + project-specific).

When to Use

• Implement use case from specs
• Build feature (backend, frontend, or both)
• Apply project patterns to new code

Usage

/dev-coding auth                     # Implement feature (will ask which UCs)
/dev-coding UC-AUTH-001              # Implement specific UC

Role: Principal Engineering Developer

You have three layers of knowledge to apply:

1. Universal Principles (references/)

• General software engineering wisdom
• backend-principles.md - API, data, security
• frontend-principles.md - UI, component, state

2. Framework-Specific Patterns (knowledge/stacks/)

• Best practices for detected stack (Next.js, Nuxt, Directus, etc.)
• Framework conventions and patterns
• Anti-patterns to avoid

3. Project-Specific Implementation (tech-context.md)

• How THIS project implements the patterns
• Project conventions and standards
• Existing code patterns

Workflow:

1. Load three layers of knowledge
2. Discover details just-in-time (Glob/Grep/Read as needed)
3. Apply all layers based on what requirement needs
4. Validate against acceptance criteria

Prerequisites

1. /dev-specs {feature} completed → specs exist
2. plans/brd/tech-context.md exists → patterns known
3. plans/features/{feature}/codebase-context.md exists (optional, helpful)

CRITICAL: Always Load Stack Knowledge

BEFORE implementing any feature:

1. Read plans/brd/tech-context.md → Identify stack(s)
2. Read knowledge/stacks/{stack}/_index.md → Load framework patterns
3. Focus on "For /dev-coding" section → Note best practices

Stack file mapping:

• "React" → knowledge/stacks/react/_index.md
• "Vue" → knowledge/stacks/vue/_index.md
• "Next.js" → knowledge/stacks/nextjs/_index.md
• "Nuxt" → knowledge/stacks/nuxt/_index.md
• "Directus" → knowledge/stacks/directus/_index.md

Deep knowledge loading (for complex features):

• First read knowledge/_knowledge.json to discover available reference files
• Load additional references when needed: knowledge/stacks/{stack}/references/*.md
• Example: For performance-critical features, load references/performance.md
• Example: For complex patterns, load references/patterns.md

If you skip this step, you'll implement using generic patterns instead of framework-specific best practices (e.g., using fetch instead of Server Actions in Next.js).

Expected Outcome

Implemented feature that meets all acceptance criteria from spec.

What "done" looks like:

• All requirements from spec completed
• All acceptance criteria pass
• Framework patterns (from knowledge/stacks/) followed
• Project patterns (from tech-context.md) followed
• Universal principles (from references/) applied
• No security vulnerabilities
• Tests passing (if applicable)
• Code quality maintained

Implementation Approach

1. Load Context (once):

Step 1: Read spec

• Get requirements, acceptance criteria, work area

Step 2: Detect and load stack knowledge

• Read plans/brd/tech-context.md
• Look for "Primary Stack", "Tech Stack", or "Stack" section
• Extract stack names (e.g., "Next.js", "Nuxt", "Directus")
• For each detected stack:
  • Read knowledge/stacks/{stack-lowercase}/_index.md (e.g., nextjs, nuxt, directus)
  • Focus on "For /dev-coding" section
  • Note best practices, patterns, anti-patterns
• If stack knowledge file doesn't exist, note it and continue

Step 3: Load universal and project specifics

• Read plans/features/{feature}/codebase-context.md → Feature-specific implementation
• Read plans/features/{feature}/architecture.md (if exists) → Architecture decisions
• Load references/backend-principles.md and/or frontend-principles.md as needed

2. Plan Work:

• If feature name given (not specific UC): Ask implementation mode
  • One by one: Implement → Test → Ask next (Recommended)
  • Multiple: Select UCs → Implement all
  • All at once: Implement all UCs
• Create TODO list from spec requirements

3. Implement (for each requirement):

• Understand: What to build, where to build it, success criteria
• Apply three layers: Universal → Framework → Project-specific
  • API work? → Universal API principles + Framework API patterns (e.g., Server Actions for Next.js) + Project's API pattern
  • UI work? → Universal component principles + Framework UI patterns (e.g., Server Components) + Project's UI pattern
  • Data work? → Universal data principles + Framework data patterns (e.g., Prisma, Directus) + Project's data pattern
  • Full-stack? → Apply all three layers across multiple concerns
• Discover: Find details just-in-time (Glob/Grep/Read)
• Build: Create/modify files following all three layers
• Validate: Check acceptance criteria, fix if needed
• Test: Write/run tests if applicable

4. Complete:

• Verify all acceptance criteria met
• Verify all files from checklist done
• Update spec with status
• Git commit (if requested)
• Move to next UC or trigger /dev-test

Just-in-Time Discovery

Don't pre-load everything. Discover when needed:

Examples:

• Need API wrapper location? → Glob: **/api.*, **/request.*
• Need schema location? → Check tech-context.md or Glob: **/schemas/*
• Need validation example? → Read existing validation file
• Need composable location? → Glob: composables/use-*.{ts,js}

Don't:

• ❌ Pre-read all files
• ❌ List all components upfront
• ❌ Memorize function names (look up when needed)

When to Escalate

During implementation, if you discover issues that affect scope:

Situation	Action
Missing detail in spec (e.g., field name unclear)	Decide based on patterns, note in commit
Spec assumes non-existent pattern (e.g., "use existing payment service" but none exists)	STOP → Ask user: "Spec references X but it doesn't exist. Options: A) Build it, B) Use alternative, C) Skip UC"
Requirement conflicts with existing code (e.g., schema mismatch)	STOP → Ask user with specific conflict details
UC scope much larger than expected (e.g., requires full OAuth refactor)	STOP → Flag to user: "This UC requires [X] which is beyond spec scope. Proceed or re-scope?"

Rule: If you can resolve in <5 minutes with confidence → do it + note in commit. Otherwise → STOP and ask.

Three-Layer Knowledge System

Layer 1: Universal Principles (references/)
    +
Layer 2: Framework Patterns (knowledge/stacks/{stack}/)
    +
Layer 3: Project Specifics (tech-context.md)
    =
Implementation

How to detect and load stack knowledge:

1. Read tech-context.md and look for stack indicators:

   **Primary Stack**: Next.js + Directus

   or

   ## Tech Stack
   - Frontend: Nuxt.js 3
   - Backend: Directus

2. Load stack knowledge files:

   • If "React" detected → Read knowledge/stacks/react/_index.md
   • If "Vue" detected → Read knowledge/stacks/vue/_index.md
   • If "Next.js" detected → Read knowledge/stacks/nextjs/_index.md
   • If "Nuxt" detected → Read knowledge/stacks/nuxt/_index.md
   • If "Directus" detected → Read knowledge/stacks/directus/_index.md

3. Focus on "For /dev-coding" section in each stack file for:

   • Framework-specific patterns
   • Best practices
   • Anti-patterns to avoid
   • Common gotchas

Apply all three layers based on requirement:

• API endpoint? → Universal API principles + Framework API patterns (Server Actions vs API routes vs composables) + Project's API pattern
• UI component? → Universal component principles + Framework UI patterns (Server vs Client Components, SFC, etc.) + Project's UI pattern
• Data access? → Universal data principles + Framework data patterns (ORM, collections, SDK) + Project's data pattern
• Full-stack? → Apply all three layers across concerns

After Implementation

When all UCs complete:

• Auto-trigger /dev-test (if available)
• If tests fail: Fix issues, re-run
• If tests pass: Suggest /dev-review

For each UC complete:

• Update spec status
• Commit if requested (follow git conventions from tech-context.md)
• Continue to next UC (based on implementation mode)

Example Flow

Requirement: "Add password reset endpoint" (Next.js project)

1. Load Knowledge:

Step 1: Read plans/brd/tech-context.md
→ Found: "Primary Stack: Next.js 14 (App Router)"

Step 2: Read knowledge/stacks/nextjs/_index.md
→ Section "For /dev-coding":
  - Use Server Actions for mutations (not Route Handlers)
  - Server Actions = "use server" directive
  - Place in lib/actions/
  - Return structured response {success, error, data}

Step 3: Read references/backend-principles.md
→ API security: validate input, rate limit, secure tokens

Step 4: Read tech-context.md patterns
→ Project uses Zod for validation
→ Project uses nodemailer for emails
→ Auth actions in lib/actions/auth.ts

2. Discover:

Glob: lib/actions/*.ts
Read: lib/actions/auth.ts (see existing login pattern)

3. Apply Three Layers:

• Universal: Input validation, secure token (crypto.randomBytes), rate limiting, expiry time
• Framework: Server Action with "use server", structured response, error handling
• Project: Zod schema validation, nodemailer email sending, follows auth.ts pattern

4. Implement:

// lib/actions/auth.ts
"use server"

export async function resetPassword(email: string) {
  // Universal: Validation
  const schema = z.string().email()
  const validated = schema.parse(email)

  // Universal: Generate secure token
  const token = crypto.randomBytes(32).toString('hex')

  // Project: Store token in DB (project pattern)
  await db.passwordReset.create({...})

  // Project: Send email (project uses nodemailer)
  await sendEmail({...})

  // Framework: Server Action response pattern
  return { success: true, data: { sent: true } }
}

5. Validate: Check acceptance criteria

Quality

Apply principles from references/ during implementation. See _quality-attributes.md for project-specific quality checklists.

Tools

Tool	Purpose	When
Read	Load spec, tech-context.md, files	Phase 1, as needed
Glob	Find files by pattern	Just-in-time discovery
Grep	Search for code patterns	Just-in-time discovery
Edit	Modify existing files	Implementation
Write	Create new files	Implementation
Bash	Run tests, git commands	Testing, committing
TodoWrite	Track implementation progress	Throughout

Anti-Patterns

❌ Reading every file upfront (discover as needed)
❌ Ignoring framework patterns (using fetch when should use Server Actions)
❌ Skipping any knowledge layer (need all three: universal + framework + project)
❌ Applying patterns from wrong framework (React patterns in Vue project)
❌ Memorizing function names (look them up when needed)
❌ Not validating against acceptance criteria (that's success)
❌ Pre-loading all components (wasteful, discover when needed)

Edge Cases

No tech-context.md:

• Error: "Run /dev-scout first to document patterns"

No spec:

• Error: "Run /dev-specs {feature} first to create implementation plan"

Stack not detected:

• Load only universal principles + project specifics
• Note: "No framework-specific patterns loaded"

Stack knowledge not available:

• If knowledge/stacks/{stack}/ doesn't exist
• Load only universal principles + project specifics
• Follow general best practices for that framework
• Note: "Framework patterns applied from general knowledge"

Spec references non-existent pattern:

• Discover pattern via Grep/Glob
• If truly doesn't exist → See "When to Escalate" section
• Note deviation in implementation notes

Success Criteria

Implementation successful when:

• ✅ All acceptance criteria met
• ✅ Universal principles applied (security, validation, performance)
• ✅ Framework patterns followed (Server Actions, composables, etc.)
• ✅ Project patterns followed (conventions from tech-context.md)
• ✅ Tests passing (if applicable)
• ✅ Code quality checks passed
• ✅ No security vulnerabilities

References

Layer 1 - Universal:

• references/backend-principles.md - General API, data, security principles
• references/frontend-principles.md - General UI, component, state principles

Layer 2 - Framework:

• knowledge/stacks/react/_index.md - React patterns (Hooks, Context, performance)
• knowledge/stacks/vue/_index.md - Vue 3 patterns (Composition API, reactivity, SFC)
• knowledge/stacks/nextjs/_index.md - Next.js patterns (Server Actions, App Router, RSC)
• knowledge/stacks/nuxt/_index.md - Nuxt patterns (composables, Nuxt UI, SSR)
• knowledge/stacks/directus/_index.md - Directus patterns (collections, flows, extensions)
• See knowledge/stacks/_index.md for all available stacks

Layer 3 - Project:

• tech-context.md - How THIS project implements patterns
• codebase-context.md - Feature-specific implementation details

Three-layer approach ensures:

• ✅ Solid engineering fundamentals (Layer 1)
• ✅ Framework best practices (Layer 2)
• ✅ Project consistency (Layer 3)