Read before modify. Test before commit. Every change needs a REQ-ID.

# Development Workflow - Virsaitis

**Module**: Development Workflow
**Load**: For all development tasks
**Version**: 3.0.0
**Updated**: 2026-02-17

---

## 🎯 Purpose

Defines discovery-first approach, TDD practices, commit workflows, and quality gates for all Virsaitis development.

---

## 🤖 Machine Policy

```
[APPROACH]
METHODOLOGY=discover_not_assume
TESTING=tdd_preferred
COMMIT_VALIDATION=mandatory
BEFORE_PR=checklist_required

[WORKFLOW_PATTERN]
DISCOVER → READ → SEARCH → VALIDATE → PLAN → CONFIRM → EXECUTE → TEST → UPDATE → VALIDATE → CONFIRM
```

---

## 🔍 Discovery-First Approach (TIER-1)

### Core Principle

**DISCOVER, don't ASSUME**

Never assume file structure, content, or requirements. Always verify before proceeding.

### Workflow Pattern

```
USER REQUEST
  ↓
1. VERIFY: File/directory existence
2. READ: Actual file content (entire file or large context)
3. SEARCH: Applicable REQ-IDs in requirements/
4. VALIDATE: Against TIER rules (core-policies.md)
5. PLAN: Minimal change scope
6. CONFIRM: If uncertain, ask user explicitly
7. EXECUTE: Using appropriate tools/workflow
8. TEST: Run validation scripts and test suite
9. UPDATE: CHANGELOG + traceability.csv
10. VALIDATE: RE-run checks after changes
11. CONFIRM: Report success with evidence
```

### Examples

**❌ ASSUMPTION FAILURE**:
```
User: "Update the config file"
AI: [Assumes location] Updating ./config.json...
Result: Wrong file, breaks system
```

**✅ DISCOVERY SUCCESS**:
```
User: "Update the config file"
AI: "CONFIRM_NEEDED: Which config file? Found:
  - virsaitis-mcp/config.json
  - virsaitis-extension/package.json
  - .vscode/settings.json"
User: "The MCP config"
AI: [Reads virsaitis-mcp/config.json] [Updates correctly]
```

---

## 🧪 Test-Driven Development (TIER-2)

### TDD Workflow (Preferred)

```
1. Write test FIRST (defines expected behavior)
2. Run test: Verify it FAILS (red)
3. Write minimum code to pass
4. Run test: Verify it PASSES (green)
5. Refactor: Improve code quality
6. Run test: Verify still PASSES
7. Repeat for next feature
```

###Benefits

- **Design clarity**: Test defines interface first
- **Confidence**: Changes protected by tests
- **Documentation**: Tests show usage examples
- **Regression prevention**: Catches breakage immediately

### When to Use TDD

**ALWAYS** for:
- MCP tool implementations
- Extension command handlers
- Governance validators
- Security-critical code

**CAN SKIP** for:
- Agent.md content (manual validation)
- Documentation updates
- Configuration changes
- Quick prototypes (but add tests before merge)

---

## 📝 Commit Workflow (TIER-1)

### Before Every Commit

**CHECKLIST** (all must pass):
```bash
# 1. Build succeeds
npm run build

# 2. Tests pass
npm test

# 3. Linter clean
npm run lint

# 4. Type check passes (TypeScript)
npm run type-check

# 5. Coverage sufficient
npm run test:coverage  # ≥70%

# 6. Security scan clean
python scripts/security-scan.py  # If available
```

**IF ANY FAIL**: Fix before committing

### Commit Message Format

```
<type>(<scope>): <description>

[optional body]

Implements: REQ-XXX-001
Related: REQ-YYY-002
```

**TYPES**:
- `feat`: New feature
- `fix`: Bug fix
- `docs`: Documentation changes
- `style`: Formatting (no code change)
- `refactor`: Code restructure (no behavior change)
- `test`: Test additions/changes
- `chore`: Build, dependencies, tooling

**SCOPES**:
- `agent`: Agent.md changes
- `mcp`: MCP server changes
- `extension`: Extension changes
- `skills`: Agent Skills changes
- `requirements`: Requirements updates
- `docs`: Documentation

> ⚡ CHECKPOINT — Does this commit include a REQ-ID? Every functional change needs traceability.

**EXAMPLES**:
```
feat(mcp): Add file operation validation tool

Implements TIER-0 protected file checking via MCP tool.
Returns validation result with tier and consequences.

Implements: REQ-MCP-012

---

fix(extension): Shield icon not showing on protected files

File decoration provider was not checking full path patterns.
Now uses path.includes() with all protected patterns.

Implements: REQ-EXT-008
```

---

## 📋 Component-Specific Workflows

### Agent Development

```
1. Draft content in memory (atomic sentences)
2. Validate atomic structure mentally
3. Check: One concept per sentence
4. Format as markdown
5. Provide code block to user
6. User: Create file manually, paste, save
7. Manual review: Atomic compliance
8. Update CHANGELOG
9. Commit with REQ-ID
```

**NEVER**: Use `create_file` for .agent.md

### MCP Development

```
1. Write test FIRST (TDD)
2. Implement MCP tool handler
3. Run: npm test
4. Run: npm run build
5. Run: npm run lint
6. Update API documentation
7. Update CHANGELOG
8. Commit with REQ-ID
```

### Extension Development

```
1. Write test FIRST (TDD)
2. Implement feature
3. Run: npm run compile
4. Run: npm test
5. Manual test: Extension Development Host
6. Update README (if user-facing)
7. Update CHANGELOG
8. Commit with REQ-ID
```

### Skills Development

```
1. Use SKILL-TEMPLATE.md
2. Fill frontmatter (name, description, metadata)
3. Write Standards & Rules (TIER-assigned)
4. Write Consequences section (per-TIER impacts)
5. Write Procedures with examples
6. Validate: skills-ref validate
7. Test: VS Code 1.109 (skill activation)
8. Update CHANGELOG
9. Commit with REQ-ID
```

---

> ⚡ CHECKPOINT — Did you read the file before modifying it? Discovery first, always.

## 📊 Quality Gates (TIER-1)

### Pre-Commit Gates

**MANDATORY** (blocks commit if failed):
- [ ] Build succeeds
- [ ] All tests pass
- [ ] Linter errors resolved
- [ ] Type checking clean (TypeScript)
- [ ] No hardcoded secrets
- [ ] CHANGELOG updated
- [ ] REQ-ID referenced

**IF GATE FAILS**: Must fix before commit

### Pre-Merge Gates

**MANDATORY** (blocks PR merge):
- [ ] All pre-commit gates passed
- [ ] Code review approved
- [ ] Coverage ≥70% overall
- [ ] Security tests 100% pass
- [ ] Documentation updated
- [ ] traceability.csv updated
- [ ] No protected file modifications without approval

### Pre-Release Gates

**MANDATORY** (blocks version release):
- [ ] All tests passing
- [ ] Coverage ≥70%
- [ ] Security scan clean
- [ ] CHANGELOG version updated
- [ ] Version numbers consistent (package.json, CHANGELOG, tags)
- [ ] Distribution package built
- [ ] Installation instructions verified

---

## 🔄 Iterative Development

### Feature Development Cycle

```
ITERATION 1: Minimum Viable
  → Write minimal test
  → Implement core logic only
  → Verify works
  → Commit

ITERATION 2: Edge Cases
  → Add edge case tests
  → Handle edge cases
  → Verify robust
  → Commit

ITERATION 3: Error Handling
  → Add error scenario tests
  → Implement error handling
  → Verify graceful failures
  → Commit

ITERATION 4: Optimization
  → Profile performance
  → Optimize bottlenecks
  → Verify no regression
  → Commit
```

**BENEFIT**: Small commits, easy to review, easy to revert

---

## 🆘 When Uncertain

> ⚡ CHECKPOINT — Tests pass? CHANGELOG updated? traceability.csv updated? Check before commit.

### Response Pattern

```
IF uncertain about:
  - File location
  - Component ownership
  - REQ-ID applicability
  - TIER classification
  - Security implications
  - Correct workflow

THEN respond:
  "CONFIRM_NEEDED: [specific question]"

  CONTEXT: [Why clarification needed]
  OPTIONS: [List options if known]
  CONSEQUENCE: [Impact of wrong choice]

  AWAITING: User response
```

**DO NOT**:
- Guess file paths
- Assume requirements
- Invent REQ-IDs
- Proceed with ambiguity

**WAIT**: For explicit user clarification

---

## 📚 Documentation Updates

### When to Update Docs

**MUST UPDATE**:
- New feature added (update README)
- API changed (update API docs)
- Configuration changed (update config guide)
- Functional change (update CHANGELOG)
- Requirement implemented (update traceability.csv)

**LOCATIONS**:
- **README.md**: Component overview, installation, usage
- **CHANGELOG.md**: Version history, changes
- **API docs**: Function signatures, parameters
- **traceability.csv**: REQ-ID implementation mapping

### Documentation Standards

**README.md STRUCTURE**:
1. Purpose and scope
2. Installation instructions
3. Configuration guide
4. Usage examples
5. API reference (if applicable)
6. Troubleshooting
7. Contributing guidelines

**CHANGELOG.md FORMAT**:
```markdown
## [Unreleased]

### Added
- Feature description (REQ-XXX-001)

### Changed
- Modification description (REQ-YYY-002)

### Fixed
- Bug fix with root cause

### Security
- Security patch (REQ-SEC-XXX)
```

---

## 🔍 Code Review Checklist

### For Reviewer

**VERIFY**:
- [ ] Tests added and passing
- [ ] Code follows component standards
- [ ] No security issues
- [ ] No hardcoded secrets
- [ ] Documentation updated
- [ ] CHANGELOG updated
- [ ] REQ-ID referenced
- [ ] No TIER-0 violations
- [ ] Atomic sentences (Agent.md)
- [ ] Proper indentation (2-space TypeScript, 4-space Python)

**QUESTIONS TO ASK**:
- Is this the simplest solution?
- Are edge cases handled?
- Is error handling robust?
- Is performance acceptable?
- Is code maintainable?

---

## 💡 Best Practices

###Small Commits

**PREFER**:
- One logical change per commit
- Commit message explains "why" not just "what"
- Easy to review (< 500 lines changed)
- Easy to revert if needed

**AVOID**:
- Large monolithic commits
- Multiple unrelated changes
- "WIP" or "misc fixes" messages

### Continuous Integration

**AFTER EVERY COMMIT**:
- CI pipeline runs automatically
- Build verifies compilation
- Tests verify functionality
- Linters verify style
- Coverage reports generated

**IF CI FAILS**:
- Fix immediately (don't commit on top)
- Don't merge until green
- Consider reverting if blocking team

### Branching Strategy

**MAIN BRANCH** (`main`):
- Always deployable
- Protected (no direct commits)
- Requires PR approval

**FEATURE BRANCHES** (`feature/description`):
- Created from `main`
- One feature per branch
- Delete after merge

**BUGFIX BRANCHES** (`fix/description`):
- Created from `main`
- Target specific bug
- Delete after merge

---

## 📖 Quick Reference

| Phase | Action | Tool/Command |
|-------|--------|--------------|
| **Discovery** | Verify file exists | `read_file`, `list_dir` |
| **Planning** | Search REQ-IDs | `grep_search requirements/` |
| **Development** | Write tests first | `vitest`, `pytest` |
| **Validation** | Run checks | `npm run build && npm test` |
| **Documentation** | Update CHANGELOG | Manual edit |
| **Commit** | Check checklist | Pre-commit hooks |

---

*Development Workflow Module v3.0.0*
*Discovery-first, TDD, quality gates*

---

## Key Rules From This Module

- Discovery first: verify file exists and read it before modifying.
- TDD preferred: write tests before implementation code.
- Every change needs a REQ-ID. Search virsaitis-requirements/ first.
- Commit messages include `Implements: REQ-XXX-YYY` or `Fixes: REQ-XXX-YYY`.
- Definitions: `.github/virsaitis-definition-library.md`

Return to hub: `.github/copilot-instructions.md`