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:

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

# 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

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

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

interface FeatureEntity {
  id: string;
  name: string;
  status: 'active' | 'inactive';
  createdAt: Date;
  // ... other fields
}

API Contracts

POST /api/features

interface CreateFeatureRequest {
  name: string;
  /* ... other fields */
}

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

Error Handling

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

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.

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.

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:

## 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

## 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

## 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)

## Conventional Commit Format

[optional scope]:

[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

## 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

## 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

## 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

### [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

### 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 when a build, test, or rollout gate fails and the root cause is not yet proven.
• Use code-quality when the feature works but the gate is blocked by maintainability, readability, duplication, or review-quality concerns.

Definition of Done

## 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

## 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

## 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 — Complete EARS requirement patterns with examples and traceability matrix
• Design Doc Guide — Technical design document writing guide with ADR template

Scripts

• Create Spec Scaffold — PowerShell script to generate requirements, design, and tasks documents

Examples

• Feature Spec Example — Complete spec-driven development example for User Authentication

Related Skills

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