# Development Workflow

> Spec-driven development lifecycle — EARS requirements, technical design docs, implementation tracking, and contribution guidelines. Use when planning features, defining requirements, or managing project lifecycle.

- Skill: `practicalswan/development-workflow` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds add practicalswan/development-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/practicalswan/development-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: practicalswan (https://skillmd.com/u/practicalswan)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/practicalswan/development-workflow

---

# Development Workflow

Structured approach to software development ensuring requirements are clearly defined, designs are meticulously planned, and implementations are thoroughly documented with proper contribution practices.

- Leverage native parallel subagent dispatch and 200k+ context windows where available.



## Activation Conditions

Use symptom -> action triggers: when one matches, apply this skill and verify with the protocol below.

**Project Planning & Requirements:**
- Starting new features or phases of work
- Defining requirements using structured notation
- Creating technical designs and architecture documents
- Managing implementation plans from concept to completion
- Ensuring thorough documentation before coding
- Understanding project structure and existing patterns

**Repository Contributions:**
- Creating issues, commits, or pull requests in a repository
- Needing to follow repository guidelines before making contributions
- Creating PRs, pushing code, or following contribution workflows
- Following project-specific contribution guidelines

**Quality Assurance:**
- Ensuring two-stage review (spec compliance first, then code quality) standards are met
- Validating tests and requirements before implementation
- Managing project decisions and trade-offs documentation
- Tracking progress and blockers

## Part 1: Spec-Driven Development

### Core Artifacts

Maintain these artifacts throughout the project lifecycle:

| Artifact | Purpose | Location |
|----------|---------|----------|
| `requirements.md` | User stories and acceptance criteria in EARS notation | Project root or `/docs/requirements/` |
| `design.md` | Technical architecture, sequence diagrams, implementation considerations | Project root or `/docs/design/` |
| `tasks.md` | Detailed, trackable implementation plan | Project root or `/docs/planning/` |

### EARS Notation for Requirements

**EARS = Easy Approach to Requirements Syntax**

#### Basic EARS Patterns

**1. Universal Requirements**
Apply to all entities without condition
- "The system **shall** validate all user input."
- "Each user **shall** have a unique email address."

**2. State-Driven Requirements**
Apply only in specific system states
- "When the user is authenticated, the system **shall** display the dashboard."
- "If the payment fails, the system **shall** retry up to 3 times."

**3. Event-Driven Requirements**
Triggered by specific events
- "When the user clicks 'Submit', the system **shall** validate the form."
- "Upon receiving a new message, the chat application **shall** update the conversation view."

**4. Optional-Feature Requirements**
Describing optional or conditional features
- "The system **may** provide offline access if supported."
- "The user **may** choose to receive email notifications."

**5. Unwanted Behavior**
Specifying what should not happen
- "The system **shall not** store passwords in plain text."
- "The application **shall not** allow simultaneous sessions from different locations unless configured."

**6. AI-Agent Requirements**
Specifying agent-visible constraints, handoff evidence, and autonomous execution limits
- "The agent **shall** run the documented verification command before claiming completion."
- "The agent **shall not** modify files outside the task scope without explicit approval."

#### Complete EARS Example

```markdown
# User Authentication Requirements

## Universal Requirements
- U-001: The system **shall** require users to provide an email address and password for login.
- U-002: The system **shall** validate email addresses using RFC 5322 format.

## Event-Driven Requirements
- E-001: **When** the user clicks "Forgot Password", the system **shall** send a password reset link to the registered email.
- E-002: **Upon** successful authentication, the system **shall** generate a session token valid for 24 hours.

## State-Driven Requirements
- S-001: **If** the user has enabled two-factor authentication, the system **shall** prompt for the verification code.
- S-002: **When** the account is locked due to too many failed attempts, the system **shall** unlock it after 30 minutes.

## Unwanted Behavior
- N-001: The system **shall not** reveal whether an email address is registered during password reset.
- N-002: The system **shall not** allow the same account to be used from more than 3 IP addresses simultaneously.

## Optional Features
- O-001: The system **may** support social login providers (Google, Facebook, GitHub).

## AI-Agent Requirements
- A-001: The agent **shall** report changed files, commands run, and unresolved risks before handoff.
```

#### EARS Grammar and Parser Example

```ebnf
requirement = id ":" [trigger ","] subject "shall" action "." ;
trigger = ("When" | "If" | "While" | "Upon") condition ;
id = ("U" | "E" | "S" | "N" | "O" | "A") "-" digit digit digit ;
```

```typescript
const earsRequirement =
  /^(?<id>[UESNOA]-\d{3}):\s(?:(?<keyword>When|If|While|Upon)\s(?<condition>.+?),\s)?(?<subject>The system|The user|The agent)\sshall\s(?<action>.+)\.$/;
```

## Overview
High-level description of what this feature does and why it's needed.

## Architecture
### System Diagram
```
User → Frontend → API Gateway → Service → Database
                              ↓
                         Cache Layer
```

### Component Structure
```
src/
├── components/
│   └── FeatureName/
│       ├── FeatureComponent.tsx
│       ├── SubComponent.tsx
│       └── styles.css
├── services/
│   └── featureService.ts
├── api/
│   └── featureApi.ts
└── types/
    └── feature.types.ts
```

## Data Models

### entities/Feature.ts
```typescript
interface FeatureEntity {
  id: string;
  name: string;
  status: 'active' | 'inactive';
  createdAt: Date;
  // ... other fields
}
```

### API Contracts

#### POST /api/features
```typescript
interface CreateFeatureRequest {
  name: string;
  /* ... other fields */
}

interface CreateFeatureResponse {
  id: string;
  status: 'created';
}
```

## Error Handling
| Error Code | HTTP Status | Description |
|-----------|-------------|-------------|
| FEATURE_001 | 409 | Feature name already exists |
| FEATURE_002 | 400 | Invalid feature data |

## Sequence Diagram
```
User → Frontend: Click "Create Feature"
Frontend → API: POST /api/features
API → Validator: Validate data
Validator → API: Valid / Invalid
API → Database: Insert feature
Database → API: Created
API → Frontend: Return feature ID
Frontend → User: Show success message
```

## Security Considerations
- Authentication required for all mutations
- Input validation on all endpoints
- Rate limiting on create operations
- Audit logging for all changes

## Performance Considerations
- Caching strategy for read operations
- Database indexing requirements
- CDN for static assets

## Agentic Considerations
- Files or directories agents may modify
- Commands agents must run before completion
- Decisions that require human approval
- Handoff evidence required for review

## Implementation Phases
1. Phase 1: Core CRUD operations
2. Phase 2: Validation and error handling
3. Phase 3: Caching layer
4. Phase 4: Testing and documentation
```

### Implementation Task Tracking

```markdown
# Tasks: [Feature Name] Implementation

## Phase 1: Foundation
- [ ] Confirm scope, dependencies, and agent boundaries
- [ ] Create data model and migration scaffold

## Phase 2: Core Functionality
- [ ] Implement core API or service path
- [ ] Add validation, errors, and persistence

## Phase 3: Frontend Integration
- [ ] Build main component
- [ ] Cover loading, empty, error, and success states

## Phase 4: Verification
- [ ] Add unit/integration/component tests for changed paths
- [ ] Run required verification commands and record evidence

## Phase 5: Release Notes
- [ ] Document behavior, migration, and user-facing changes

Full scaffold reference: `examples/feature-spec-example.md` or `scripts/create-spec-scaffold.ps1`.
```

---

## Part 2: Repository Contribution Guidelines

<!-- MCP:START -->

<!-- PORTABILITY:START -->
## Cross-Client Portability

This skill is written to stay usable across GitHub Copilot, Claude Code, and Codex.

- GitHub Copilot: keep the folder in a Copilot-visible skill path or wrap the
  workflow in project instructions when folder discovery is unavailable.
- Claude Code: keep the folder in a local skills directory or a compatible plugin source.
- Codex: install or sync the folder into
  `$CODEX_HOME/skills/development-workflow` and restart Codex after major changes.

<!-- PORTABILITY:END -->

## MCP Availability And Fallback

Preferred MCP Server: None required

- Fallback prompt: "Use the Development Workflow skill without MCP. Rely on its local instructions, bundled resources, standard shell or editor tools, and direct verification. Show the evidence used before concluding."
- Do not claim an MCP operation was used when the active host does not expose it.
- Treat local files, tests, rendered outputs, logs, or screenshots as the fallback evidence path.

<!-- MCP:END -->

## Anti-Patterns

- Starting work before the plan or gate is clear: Execution drifts when success criteria are implied instead of explicit.
- Treating verification as optional cleanup: The last mile is where regressions and missing updates are usually hiding.
- Mixing planning, implementation, and release work in one jump: You lose the causal chain that explains why a change is safe.

## Verification Protocol

Before claiming "skill applied successfully":

1. Pass/fail: The Development Workflow starts from explicit success criteria, constraints, and stop conditions.
2. Pass/fail: Required evidence is collected before any completion, approval, or readiness claim.
3. Pass/fail: The next action follows the documented gate order without skipping review or verification steps.
4. Pressure-test scenario: Apply the workflow under time pressure with one failing check and one tempting shortcut.
5. Success metric: Zero rationalizations; blocked, failed, or unverified work is reported as such.


### Pre-Contribution Checklist

Before creating any PR or making changes:

```markdown

## Pre-Submission Checklist

### Repository Understanding
- [ ] Read README.md for project overview
- [ ] Read CONTRIBUTING.md for contribution rules
- [ ] Reviewed issue and PR templates
- [ ] Checked for existing related issues or PRs

### Environment Setup
- [ ] forked repository (if required)
- [ ] cloned repository locally
- [ ] setup development environment
- [ ] installed all dependencies

### Development Standards
- [ ] Understand coding style conventions
- [ ] Familiar with branching strategy
- [ ] Aware of commit message conventions
- [ ] Know testing requirements
```

### Issue Creation Workflow

#### When to Create Issues
- New feature requests
- Bug reports
- Documentation gaps
- Security vulnerabilities
- Performance concerns

#### Issue Template

```markdown
## Issue: [Brief Title]

### Type: [Feature Request / Bug Report / Question / Documentation]

### Priority: [Low / Medium / High / Critical]

### Description
[Detailed description of the issue or feature request]

### Reproduction Steps (for bugs)
1. [First step]
2. [Second step]
3. [Third step]

### Expected Behavior
[What should happen]

### Actual Behavior
[What actually happened]

### Environment
- OS: [e.g., Windows 10, macOS 12.5]
- Browser: [e.g., Chrome 120, Firefox 115]
- Version: [If applicable]

### Additional Context
[Any other information that might be helpful]
- Screenshots
- Error messages
- Logs
```

### Branching Strategy

```markdown
## Branch Naming Convention

### Feature Branches
`feature/[JIRA-TICKET]/[short-description]`
Examples:
- feature/PROJ-123/user-authentication
- feature/PROJ-456/dark-mode-support

### Bugfix Branches
`bugfix/[JIRA-TICKET]/[issue-description]`
Examples:
- bugfix/PROJ-789/login-redirect-loop
- bugfix/PROJ-321/memory-leak-report

### Hotfix Branches (production issues)
`hotfix/[JIRA-TICKET]/[critical-description]`
Examples:
- hotfix/PROJ-999/security-vulnerability
- hotfix/PROJ-888/database-down

### Release Branches
`release/v[major].[minor]`
Examples:
- release/v1.2.0
- release/v2.0.0

### Branch Protection Rules
- Protect `main` and `develop` branches
- Require pull request reviews (at least 1 approval)
- Require status checks to pass (CI builds, tests)
- Require branches to be up-to-date before merging
```

### Commit Message Standards (Conventional Commits)

```markdown
## Conventional Commit Format

```
<type>[optional scope]: <description>

[optional body]

[optional footer(s)]
```

### Commit Types

| Type       | Purpose                        | Example                          |
|------------|--------------------------------|----------------------------------|
| `feat`     | New feature                     | `feat(auth): add OAuth2 support`   |
| `fix`      | Bug fix                         | `fix(api): resolve null reference`  |
| `docs`     | Documentation only              | `docs(readme): update setup guide`  |
| `style`    | Formatting/style (no logic)      | `style(ui): fix indentation`       |
| `refactor` | Code refactor (no feature/fix)   | `refactor(svc): extract helpers`  |
| `perf`     | Performance improvement          | `perf(db): add index on email`    |
| `test`     | Add/update tests                | `test(auth): add unit tests`      |
| `build`    | Build system/dependencies        | `build(ci): upgrade Node to v20`  |
| `ci`       | CI/config changes              | `ci(github): add workflow for PRs`|
| `chore`    | Maintenance/misc               | `chore(deps): update packages`    |
| `revert`   | Revert commit                 | `revert: feat(login)`             |

### Breaking Changes
```
feat(api)!: remove deprecated v1 endpoint

BREAKING CHANGE: v1 endpoints are no longer supported. Use v2.
```

### Good Commit Examples
```
feat(auth): add refresh token mechanism
- Implement JWT refresh tokens
- Add storage for access tokens
- Update token validation logic

fix(ui): resolve mobile navigation issue
- Mobile menu was not closing after clicking links
- Added event listener to handle link clicks
- Tested on iOS Safari and Chrome Mobile

docs(readme): update installation instructions
- Clarified Node.js version requirement
- Added troubleshooting section
```

### Bad Commit Examples (Don't use)
```
update 2
fixed bug
wip
changes
final
work in progress
```

### Commit Workflow
```bash
# Stage changes
git add .

# Interactive staging (optional)
git add -i

# Commit with good message
git commit -m "feat(auth): implement OAuth2 login"

# Or use multi-line for body and footer
git commit -m "fix(db): optimize query performance

Added composite index on user_email and created_at
Reduced query time from 500ms to 50ms

Closes issue #123"
```

---

## Part 3: Pull Request Process

### Creating Pull Requests

#### PR Checklist

```markdown
## Pull Request Checklist

### Before Submitting
- [ ] Branch is up-to-date with target branch
- [ ] Code compiles without errors
- [ ] All tests pass locally
- [ ] Linters pass without errors
- [ ] Documentation updated (README, API docs, code comments)
- [ ] Self-review completed

### PR Description
- [ ] Clear title following conventional commits
- [ ] Description explains "why" not just "what"
- [ ] Screenshots for UI changes included
- [ ] Breaking changes documented
- [ ] Related issues referenced (e.g., "Closes #123")
- [ ] Testing instructions provided

### Code Quality
- [ ] Follows project coding standards
- [ ] No commented-out code
- [ ] No console.log statements
- [ ] meaningful variable and function names
- [ ] No sensitive data exposed

### Testing
- [ ] New features tested
- [ ] Bug fixes verified
- [ ] Edge cases covered
- [ ] Manual testing completed as described
```

#### PR Template

```markdown
## Description
[Provide a brief description of the changes in this PR]

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Breaking change
- [ ] Documentation
- [ ] Refactoring
- [ ] Performance improvement

## Issue
[Closes #xxx] or [Related to #xxx]

## Changes Made
### Main Changes
- [Describe the main changes implemented]

### Technical Details
[Any technical details reviewers should know]

### Breaking Changes
[Any breaking changes and migration steps]

## Testing
### Manual Testing Steps
1. [Step 1]
2. [Step 2]

### Automated Testing
- [ ] Unit tests added and passing
- [ ] Integration tests added and passing
- [ ] E2E tests added and passing

## Screenshots
[Include before/after screenshots for UI changes]

## Checklist
- [ ] I have read the contributing guidelines
- [ ] My code follows the project style guidelines
- [ ] I have performed a self-review
- [ ] I have commented my code appropriately
- [ ] Changes have no linting errors
- [ ] All tests are passing
- [ ] Changes do not break existing functionality
```

### two-stage review (spec compliance first, then code quality) Guidelines

#### For Reviewers

```markdown
## two-stage review (spec compliance first, then code quality) Principles

### Be Constructive
- Focus on improving code, not criticizing it
- Provide specific examples and suggestions
- Ask questions rather than making demands
- Acknowledge good code and smart solutions

### Review Focus Areas

#### Correctness
- [ ] Logic is correct and handles edge cases
- [ ] Error handling is adequate
- [ ] No obvious bugs or race conditions
- [ ] API contracts are maintained

#### Code Quality
- [ ] Code is readable and maintainable
- [ ] Naming follows conventions
- [ ] Complexity is reasonable
- [ ] No code duplication

#### Architecture
- [ ] Follows established patterns
- [ ] Good separation of concerns
- [ ] Proper abstractions used
- [ ] No tight coupling

#### Security
- [ ] No security vulnerabilities
- [ ] Input validation present
- [ ] Authentication/authorization correct
- [ ] No sensitive data exposure

### Review Priority Comments
🔴 **Blocker**: Must be fixed before merge
🟡 **Concern**: Discuss before merge
🟢 **Suggestion**: Nice to have, not blocking
```

---

## Part 4: Documentation Standards

### Documentation Templates

#### Action Documentation
```markdown
### [TYPE] - [ACTION] - [TIMESTAMP]

**Objective**: [Goal being accomplished]

**Context**: [Current state, requirements, reference to prior steps]

**Decision**: [Approach chosen and rationale]

**Execution**: [Steps taken with parameters and commands]

**Output**: [Complete results, logs, metrics]

**Validation**: [Success verification and results]

**Next**: [Continuation plan to next action]
```

#### Decision Record
```markdown
### Decision - [TIMESTAMP]

**Decision**: [What was decided]

**Context**: [Situation and driving data]

**Options**:
- Option 1: [Description] - [Pros/Cons]
- Option 2: [Description] - [Pros/Cons]
- Option 3: [Description] - [Pros/Cons]

**Rationale**: [Why selected option is superior]

**Impact**: [Anticipated consequences]

**Review**: [Reassessment conditions]
```

#### Summary Formats

**Streamlined Action Log (for changelogs):**
`[TYPE][TIMESTAMP] Goal: [X] → Action: [Y] → Result: [Z] → Next: [W]`

**Quick Summary (for updates):**
**What**: [Brief description]
**Why**: [Context/rationale]
**How**: [Approach taken]
**Status**: [Current state]
**Next**: [Upcoming step]

---

## Dependency Management

- Pin the runtime, package manager, and critical libraries in the design doc before implementation starts.
- Record upgrade constraints, required codemods, and any package that needs special review because it changes build, auth, or persistence behavior.
- Prefer a small scheduled update cadence over infrequent large jumps so the test surface stays understandable.

## Vulnerability Scanning

- Run dependency scans as part of the normal quality gate, not only before release.
- Triage findings by exploitability and reachability instead of blindly applying every patch immediately.
- Track accepted risks with owners and revisit dates when a fix cannot ship in the current cycle.

## Accessibility Testing

- Add keyboard, focus-order, semantic HTML, and screen-reader expectations to the feature definition instead of treating accessibility as a polishing pass.
- Pair automated tooling such as axe or Playwright accessibility checks with manual review of the critical flows.
- Keep accessibility bugs inside the same Definition of Done as functional bugs for the feature.

## Internationalization (i18n) Considerations

- Identify translatable strings, locale-aware formatting, and right-to-left layout risks during planning.
- Keep UI copy, date or number formatting, and fallback language behavior outside hard-coded components.
- Verify overflow, truncation, and validation messages in at least one non-default locale before release.

## Part 5: Quality Gates

### Cross-Skill Gates

- Use [systematic-debugging](../systematic-debugging/SKILL.md) when a build, test, or rollout gate fails and the root cause is not yet proven.
- Use [code-quality](../code-quality/SKILL.md) when the feature works but the gate is blocked by maintainability, readability, duplication, or review-quality concerns.

### Definition of Done

```markdown
## Definition of Done (DoD)

### Development
- [ ] Code written and committed
- [ ] Code follows project style guide
- [ ] Code compiles without errors
- [ ] No console errors or warnings
- [ ] Self-review completed

### Testing
- [ ] Unit tests written and passing
- [ ] Integration tests written and passing
- [ ] Manual testing completed
- [ ] Edge cases identified and handled
- [ ] Test coverage meets project threshold (>80%)

### Documentation
- [ ] README updated if API changed
- [ ] API documentation updated
- [ ] Code comments added/updated
- [ ] User documentation updated if needed

### two-stage review (spec compliance first, then code quality)
- [ ] Pull request created
- [ ] At least one approval received
- [ ] All review comments addressed
- [ ] CI/CD pipeline passes
- [ ] Merged to appropriate branch

### Deployment
- [ ] Deployment tested in staging
- [ ] Smoke tests passed
- [ ] Performance validated
- [ ] Monitoring/alerting configured
- [ ] Rollback procedure documented
```

### Quality Checklist

```markdown
## Code Quality Checklist

### Functionality
- [ ] All acceptance criteria met
- [ ] Requirements from design document fulfilled
- [ ] Edge cases handled
- [ ] Error states handled gracefully

### Usability
- [ ] User-friendly error messages
- [ ] Clear feedback for actions
- [ ] Accessible (keyboard, screen reader)
- [ ] Responsive design verified

### Performance
- [ ] Meet performance requirements
- [ ] No memory leaks
- [ ] Efficient algorithms used
- [ ] Appropriate caching

### Security
- [ ] Input validation
- [ ] Output encoding (prevent XSS)
- [ ] Authentication/authorization implemented
- [ ] No sensitive data in logs
- [ ] Dependencies audited and up-to-date

### Maintainability
- [ ] Code is readable
- [ ] Good variable/function names
- [ ] Appropriate abstractions
- [ ] No code duplication
- [ ] Adequate comments

### Testing
- [ ] Unit tests for critical paths
- [ ] Integration tests for API
- [ ] E2E tests for user flows
- [ ] Tests are reliable and not flaky
```

---

## Part 6: Project Lifecycle Management

### Phase-based Development

```markdown
## Development Phases

### Phase 1: Requirements & Planning
- Gather requirements from stakeholders
- Document in EARS notation
- Create technical design
- Identify risks and dependencies
- Estimate effort and timeline

### Phase 2: Development
- Set up feature branches
- Implement core functionality
- Write tests alongside code
- two-stage review (spec compliance first, then code quality) and iteration

### Phase 3: Testing & QA
- Run automated tests
- Perform manual testing
- Conduct QA review
- Fix identified issues
- Performance testing

### Phase 4: Deployment
- Deploy to staging
- Execute smoke tests
- Get stakeholder approval
- Deploy to production
- Monitor for issues

### Phase 5: Post-Release
- Monitor metrics and logs
- Collect user feedback
- Address critical bugs
- Document lessons learned
- Update process improvements
```

## Development Workflow Best Practices

### Before Coding
- [ ] Requirements clearly defined and reviewed
- [ ] Technical design documented
- [ ] Dependencies identified
- [ ] Acceptance criteria established
- [ ] Testing strategy planned

### During Development
- [ ] Small, frequent commits
- [ ] Write tests alongside code
- [ ] Follow coding standards
- [ ] Continuous self-review
- [ ] Request early feedback

### Before Release
- [ ] All tests passing
- [ ] two-stage review (spec compliance first, then code quality) completed
- [ ] Documentation updated
- [ ] Security review (if needed)
- [ ] Release notes prepared

### After Release
- [ ] Monitor production carefully
- [ ] Be ready to rollback
- [ ] Document issues and fixes
- [ ] Update metrics and dashboards
- [ ] Conduct retrospective

---

## References & Resources

### Documentation
- [EARS Notation Reference](./references/ears-notation-reference.md) — Complete EARS requirement patterns with examples and traceability matrix
- [Design Doc Guide](./references/design-doc-guide.md) — Technical design document writing guide with ADR template

### Scripts
- [Create Spec Scaffold](./scripts/create-spec-scaffold.ps1) — PowerShell script to generate requirements, design, and tasks documents

### Examples
- [Feature Spec Example](./examples/feature-spec-example.md) — Complete spec-driven development example for User Authentication

---

## Related Skills

- [code-quality](../code-quality/SKILL.md): Use it when the workflow also needs two-stage review (spec compliance first, then code quality), maintainability, and refactoring guidance.
- [systematic-debugging](../systematic-debugging/SKILL.md): Use it when the workflow also needs root-cause debugging before proposing fixes.
- [test-driven-development](../test-driven-development/SKILL.md): Use it when the workflow also needs test-first implementation and regression safety.
- [verification-before-completion](../verification-before-completion/SKILL.md): Use it when the workflow also needs final evidence checks before claiming completion.