Development Workflow

Purpose: Establish efficient, high-quality development practices using AI code assistant agents and tools.

Category: Meta-Skill (Development Process)

---

When to Use This Skill

This skill applies throughout the entire development lifecycle:

• Starting any new feature or bug fix
• Exploring unfamiliar code
• Making architectural decisions
• Committing changes
• Creating pull requests
• Reviewing code quality

Triggers:

• User requests a new feature
• User asks "where is..." or "how does..." questions
• You're about to implement without planning
• You're about to commit changes
• User asks for a PR

---

Core Principle

Use the right tool for the job. Don't do manually what specialized agents can do better.

---

Workflow 1: New Feature Development

Triggers

• "Add...", "Build...", "Create...", "Implement [new thing]"
• User describes functionality that doesn't exist yet

Decision Point: Should I use /feature-dev?

Use /feature-dev if:

• ✅ Feature requires multiple files
• ✅ Unclear how it should integrate with existing code
• ✅ Need to understand existing patterns first
• ✅ User hasn't specified exact implementation approach

Skip /feature-dev if:

• ❌ Trivial change (typo fix, single-line tweak)
• ❌ User provided extremely detailed implementation instructions
• ❌ Pure research/exploration task (use code-explorer instead)

Workflow

If using /feature-dev:

1. Invoke Skill tool with skill="feature-dev:feature-dev"
2. Let the feature-dev workflow handle:
   - Codebase exploration
   - Clarifying questions
   - Architecture design
   - Implementation
   - Code review
3. Done - feature-dev handles end-to-end

If NOT using /feature-dev (simple change):

1. Read relevant files to understand current implementation
2. Ask clarifying questions if anything is ambiguous
3. Implement the change
4. Run build/lint/tests
5. Consider code-reviewer agent for non-trivial changes

Anti-pattern:

❌ User: "Add a new selector component"
   Assistant: *immediately starts writing code*

✅ User: "Add a new selector component"
   Assistant: "I'll use /feature-dev to explore the codebase,
              understand existing patterns, and design the implementation."

---

Workflow 2: Code Exploration & Understanding

Triggers

• "Where is...", "Explain how X works", "Map the project", "Find usage of..."
• Questions about code structure or flow

Decision Point: Manual search vs code-explorer?

Use code-explorer agent if:

• ✅ Question requires understanding code flow across multiple files
• ✅ Need to trace execution paths
• ✅ "How does X work?" questions
• ✅ Finding all usages of a pattern

Manual search (Glob/Grep) if:

• ✅ Needle query - looking for specific file/class/function name
• ✅ You know exactly what to search for
• ✅ Single-file investigation

Workflow

For exploration (use code-explorer):

1. Launch Task tool with subagent_type="Explore"
2. Provide clear question: "How does authentication work?"
3. Specify thoroughness: "medium" or "very thorough"
4. Read files identified by agent
5. Summarize findings

For needle queries (manual search):

1. Use Glob for file patterns: "**/*auth*.js"
2. Use Grep for code patterns: "getUser.*session"
3. Read matched files
4. Provide answer

---

Workflow 3: Architecture & Planning

Triggers

• "Plan...", "Design...", "Refactor strategy", "How should I structure..."
• Before implementing non-trivial features

Decision Point: Should I enter plan mode?

Use EnterPlanMode if ANY of:

• ✅ New feature with multiple valid approaches
• ✅ Architectural decisions required
• ✅ Changes affect multiple files (3+)
• ✅ Unclear requirements need exploration first
• ✅ User preferences matter for implementation approach

Skip plan mode if:

• ❌ Single-line fix
• ❌ User provided very specific instructions
• ❌ Pure research task

Workflow

1. Use EnterPlanMode tool
2. In plan mode:
   a. Explore codebase thoroughly
   b. Understand existing patterns
   c. Identify decision points
   d. Use AskUserQuestion for clarifications
   e. Design implementation approach
   f. Write plan to plan file
   g. Use ExitPlanMode
3. Wait for user approval
4. Implement according to approved plan

---

Workflow 4: Code Quality & Review

Triggers

• Completed non-trivial implementation
• Before creating PR
• User asks "review this"

Decision Point: When to use code-reviewer?

Use code-reviewer proactively when:

• ✅ Just completed a feature (before user asks)
• ✅ Added >50 lines of new code
• ✅ Modified critical paths (update handlers, hooks, migrations)
• ✅ About to create PR
• ✅ Touched performance-sensitive code

Workflow

1. Complete implementation
2. Launch Task tool with subagent_type="pr-review-toolkit:code-reviewer"
3. Specify files to review (usually unstaged git diff)
4. Review agent findings
5. Fix high-priority issues
6. Commit changes

---

Workflow 5: Version Control & Commits

Triggers

• User asks to commit changes
• User asks to create PR
• Feature is complete and tested

Git Discipline Rules

NEVER:

• ❌ Run raw git commit via Bash without crafted message
• ❌ Skip commit message template (must include attribution)
• ❌ Commit without running git status + git diff first
• ❌ Commit files with secrets (.env, credentials)
• ❌ Use --no-verify to skip hooks (unless user explicitly requests)
• ❌ Force push to main/master

ALWAYS:

• ✅ Use Skill tool for commits: skill="commit-commands:commit"
• ✅ Run git status and git diff in parallel first
• ✅ Draft commit message based on actual changes (not assumptions)
• ✅ Follow commit message style from git log
• ✅ Include attribution footer
• ✅ Verify no unintended files are staged

Commit Workflow

1. Run in parallel:
   - git status (see untracked files)
   - git diff (see staged + unstaged changes)
   - git log -10 --oneline (see commit style)

2. Analyze changes and draft commit message:
   - Type: feat/fix/refactor/docs/chore/test
   - Summary: What changed and why (focus on "why", not "what")
   - Keep under 72 characters for summary line

3. Stage relevant files (git add)

4. Commit with proper message and attribution

5. Run git status after commit to verify success

---

Workflow 6: External Knowledge & Research

Triggers

• Uncertain about API usage
• Need current information (library versions, recent changes)
• User asks about external tools/libraries

Decision Point: Search vs Assume

ALWAYS search (don't assume) for:

• ✅ Framework API usage (changes between versions)
• ✅ Recent library features
• ✅ Browser compatibility issues
• ✅ Security best practices
• ✅ Anything you're unsure about

Safe to assume (from training):

• ✅ JavaScript/ES6 syntax
• ✅ General web development patterns
• ✅ Git fundamentals
• ✅ Common npm commands

Workflow

1. Identify knowledge gap
2. Use WebSearch or documentation tools
3. Cite sources in response
4. Apply findings to implementation

---

Workflow 7: Testing & Verification

Triggers

• After implementing any feature
• Before committing
• Before creating PR

Testing Checklist

Minimum (ALWAYS):

1. Build (if applicable)
2. Lint (if applicable)
3. Describe what to test manually

Workflow

1. Implement feature
2. Run build/lint commands
3. Describe manual testing steps
4. If update handlers involved:
   - Review safety checklist
   - Recommend appropriate tests

---

Decision Trees

"Should I use an agent?"

Feature request
├─ Trivial (1-5 lines)? → Implement directly
├─ Exploration needed? → code-explorer
├─ Architecture decision? → feature-dev (includes exploration + planning)
├─ Just planning? → EnterPlanMode
└─ Implementation done? → code-reviewer (proactive)

Code question
├─ Needle query (know what to find)? → Glob/Grep
├─ "How does X work?" → code-explorer
└─ "Where is X?" → code-explorer

Commit/PR
├─ Ready to commit? → Use commit skill (never raw git)
├─ Ready for PR? → Analyze full diff, draft description
└─ Unsure if ready? → code-reviewer first

"Should I search or assume?"

Knowledge question
├─ Framework API? → SEARCH (changes between versions)
├─ Recent library features? → SEARCH
├─ Security concern? → SEARCH
├─ Browser compatibility? → SEARCH
├─ Basic JavaScript? → Assume (from training)
└─ Git basics? → Assume

---

Anti-Patterns to Avoid

1. Skipping Exploration

Problem: Implementing without understanding existing patterns

❌ User: "Add a new field component"
   Assistant: *immediately writes new code from scratch*

✅ User: "Add a new field component"
   Assistant: *uses code-explorer to understand existing patterns first*

2. Manual Work Over Agents

Problem: Doing manually what agents do better

❌ User: "Where are errors handled?"
   Assistant: *manually greps for "error", reads 3 files*

✅ User: "Where are errors handled?"
   Assistant: *launches code-explorer to trace error handling comprehensively*

3. Assuming Knowledge

Problem: Using outdated or incorrect API information

❌ Assistant: "I'll use the deprecated API pattern"

✅ Assistant: "Let me verify the current API pattern..."

4. Sloppy Commits

Problem: Raw git commands, poor messages, no attribution

❌ Assistant: *runs bash* `git commit -m "fix"`

✅ Assistant: *uses commit skill*
   Assistant: *analyzes changes, drafts message, includes attribution*

5. No Testing Guidance

Problem: Declaring done without verification steps

❌ Assistant: "Feature complete!"

✅ Assistant: "Feature complete. To test:
   1. Run the build
   2. Open the application
   3. Verify the new feature works"

---

Quick Reference Checklist

Starting Work

• Is this a feature? → Consider /feature-dev
• Is this exploration? → Use code-explorer
• Is this complex? → Use EnterPlanMode
• Do I need external knowledge? → Search first

During Implementation

• Reading existing code before modifying
• Following existing patterns
• Using project conventions

Before Committing

• Run build (if applicable)
• Run lint (if applicable)
• Proactive code review (if non-trivial)
• Git status + git diff reviewed
• Commit message drafted with attribution
• Testing guidance provided

Creating PR

• Analyzed FULL diff (not just latest commit)
• PR description drafted with test plan
• Build and lint passing

---

Success Criteria

You're following this workflow correctly when:

• ✅ Features are explored before implementing
• ✅ Code is reviewed proactively (before user asks)
• ✅ Commits are clean with proper messages
• ✅ PRs include comprehensive descriptions
• ✅ Testing guidance is always provided
• ✅ External knowledge is verified, not assumed
• ✅ Specialized agents are used appropriately

---

Last Updated: 2026-01-04 Status: Active - use throughout development lifecycle