# BUG-028 Implementation Plan

## Problem Statement

The spec/AGENT.md files (spec/CLAUDE.md, spec/CURSOR.md, etc.) currently contain only a 17-line stub. They should contain the full 2069-line "Project Management and Specification Guidelines for fspec" content with agent-specific transformations applied.

## Architecture Understanding

**TWO DIFFERENT FILE TYPES:**

1. **Slash Command Files** (.claude/commands/fspec.md, .cursor/commands/fspec.md)
   - Purpose: ACDD workflow documentation for /fspec slash command
   - Content: 1019 lines
   - Generated by: `generateSlashCommandContent()` in src/commands/init.ts
   - Template: `getSlashCommandTemplate()` from src/utils/slashCommandTemplate.ts
   - Status: ✅ CORRECT (already working as expected)

2. **Project Documentation Files** (spec/CLAUDE.md, spec/CURSOR.md, spec/AIDER.md)
   - Purpose: Project Management and Specification Guidelines
   - Content: 2069 lines
   - Generated by: `generateAgentDoc()` in src/utils/templateGenerator.ts
   - Template: Currently uses BASE_AGENT_TEMPLATE (17-line stub) ❌ WRONG
   - Should use: NEW getProjectManagementTemplate() ✅ FIX NEEDED

## Current (Wrong) Implementation

```typescript
// src/utils/templateGenerator.ts
export async function generateAgentDoc(agent: AgentConfig): Promise<string> {
  const { getSlashCommandTemplate } = await import('./slashCommandTemplate');
  let content = getSlashCommandTemplate(); // ❌ WRONG - uses slash command template

  content = stripSystemReminders(content, agent);
  content = removeMetaCognitivePrompts(content, agent);
  content = replacePlaceholders(content, agent);
  return content;
}
```

## Correct Implementation

### Step 1: Create Project Management Template System

Create `src/utils/projectManagementTemplate.ts` following the same pattern as `slashCommandTemplate.ts`:

```typescript
// src/utils/projectManagementTemplate.ts
import { getIntroSection } from './projectManagementSections/intro';
import { getProjectManagementSection } from './projectManagementSections/projectManagement';
import { getReverseAcddSection } from './projectManagementSections/reverseAcdd';
import { getSpecificationWorkflowSection } from './projectManagementSections/specificationWorkflow';
// ... import all other sections

export function getProjectManagementTemplate(): string {
  return [
    getIntroSection(),
    getProjectManagementSection(),
    getReverseAcddSection(),
    getSpecificationWorkflowSection(),
    // ... all sections
  ].join('\n');
}
```

### Step 2: Break spec/CLAUDE.md into Section Files

Create directory `src/utils/projectManagementSections/` with files:

- `intro.ts` - Lines 1-8 (title, intro)
- `projectManagement.ts` - Lines 9-200 (Project Management Workflow)
- `reverseAcdd.ts` - Lines 201-400 (Reverse ACDD section)
- `specificationWorkflow.ts` - Lines 401-600 (Gherkin specs)
- `coverageTracking.ts` - Lines 601-800 (Coverage system)
- `fileStructure.ts` - Lines 801-900 (Directory layout)
- `prefillDetection.ts` - Lines 901-1000 (Prefill system)
- `temporalOrdering.ts` - Lines 1001-1100 (FEAT-011)
- `estimation.ts` - Lines 1101-1200 (Story point validation)
- `formatting.ts` - Lines 1201-1300 (Formatting rules)
- `enforcement.ts` - Lines 1301-1400 (Enforcement rules)
- `effectiveScenarios.ts` - Lines 1401-1500 (Writing scenarios)
- `mappingToTests.ts` - Lines 1501-1600 (Test mapping)
- `updatingSpecs.ts` - Lines 1601-1700 (Change process)
- `dogfooding.ts` - Lines 1701-1800 (Using fspec to manage fspec)
- `jsonBackedSystem.ts` - Lines 1801-1900 (JSON documentation)
- `attachments.ts` - Lines 1901-2000 (Attachment support)
- `lifecycleHooks.ts` - Lines 2001-2100 (Hooks system)
- `virtualHooks.ts` - Lines 2101-2200 (Virtual hooks)
- `gitCheckpoints.ts` - Lines 2201-2300 (Checkpoints)
- `references.ts` - Lines 2301-2400 (References and enforcement)

Each file exports a function like:
```typescript
export function getIntroSection(): string {
  return `# Project Management and Specification Guidelines for fspec

This document defines the complete workflow...`;
}
```

### Step 3: Update generateAgentDoc()

```typescript
// src/utils/templateGenerator.ts
export async function generateAgentDoc(agent: AgentConfig): Promise<string> {
  // Import getProjectManagementTemplate (NEW)
  const { getProjectManagementTemplate } = await import('./projectManagementTemplate');

  // Use Project Management template (NOT slash command template)
  let content = getProjectManagementTemplate();

  // Apply transformations
  content = stripSystemReminders(content, agent);
  content = removeMetaCognitivePrompts(content, agent);
  content = replacePlaceholders(content, agent);

  return content;
}
```

### Step 4: Remove BASE_AGENT_TEMPLATE

The 17-line `BASE_AGENT_TEMPLATE` at the top of templateGenerator.ts can be deleted since:
- Root stubs are generated inline in `installRootStub()` (init.ts:113-131)
- spec/AGENT.md files now use `getProjectManagementTemplate()`

## Testing Strategy

### Tests to Update

1. **src/utils/__tests__/templateGenerator-comprehensive.test.ts**
   - Currently tests expect spec/AGENT.md to have >900 lines (slash command content)
   - Should expect spec/AGENT.md to have >2000 lines (Project Management content)
   - Should verify content contains "Project Management and Specification Guidelines"
   - Should NOT contain "# fspec Command" (that's slash command header)

2. **src/commands/__tests__/init-bundling.test.ts**
   - Line 73-75: Change from >900 lines to >2000 lines
   - Line 97-99: Change from >900 lines to >2000 lines

3. **src/commands/__tests__/init-multi-agent.test.ts**
   - Line 40: Change from >900 lines to >2000 lines
   - Line 123: Change from >900 lines to >2000 lines

### Validation

After implementation:
- spec/CLAUDE.md should be ~2069 lines
- spec/CURSOR.md should be ~2069 lines
- spec/AIDER.md should be ~2069 lines
- .claude/commands/fspec.md should be ~1019 lines (unchanged)
- All tests should pass

## Implementation Order

1. Create `src/utils/projectManagementSections/` directory
2. Break spec/CLAUDE.md into section files (20 files)
3. Create `src/utils/projectManagementTemplate.ts`
4. Update `generateAgentDoc()` in templateGenerator.ts
5. Remove `BASE_AGENT_TEMPLATE` constant
6. Update test expectations (>2000 lines, correct content)
7. Run tests and verify all pass
8. Test with `fspec init --agent=claude` and verify spec/CLAUDE.md is 2069 lines

## Expected Outcome

After fix:
- ✅ spec/CLAUDE.md: 2069 lines of Project Management Guidelines
- ✅ spec/CURSOR.md: 2069 lines (with Cursor-specific transformations)
- ✅ spec/AIDER.md: 2069 lines (with Aider-specific transformations)
- ✅ .claude/commands/fspec.md: 1019 lines of ACDD workflow (unchanged)
- ✅ No circular references
- ✅ All tests passing
- ✅ No filesystem dependencies (all embedded as TypeScript literals)