development-workflow

What this skill does

# 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

## Anti-Patterns

- Starting