Skip to content

ADR 004: Project Management Methodology

Metadata

  • Status: Accepted & Implemented
  • Date: 2025-12-25
  • Type: Architecture Decision Record (ADR)

This note explores the differences between the Spec Kit methodology (promoted by GitHub Next for AI-native development) and the Manual "Plan-First" Protocol currently used in the ChatKcal project.

1. Context & Definitions

The "Spec Kit" Methodology

Spec Kit (and the broader concept of "Spec-Driven Development" for AI) posits that natural language specifications should be the primary source of truth, not the code itself.

  • Core Concept: You write a detailed, structured markdown spec defining intent, interface, and constraints. An AI agent consumes this spec to generate implementation, tests, and validation logic.
  • Goal: Reduce "vibe coding" (iterating until it feels right) by front-loading clarity. The artifact is the Spec, and the code is a derivative product.
  • Workflow: Spec -> AI Implementation -> Auto-Verification -> Human Review.

The "ChatKcal" (Current) Methodology

Our current approach is a Manual "Plan-First" Protocol, where documentation serves as a project management & communication layer rather than a direct compiler input.

  • Core Concept: Documentation (docs/project_management) acts as a "Mission Control". We manually create Work Logs to enforce a cognitive pause: Plan (Context/Approach) → Approve → Execute.
  • Goal: Ensure the AI (and human pair) fully understands the architectural implications before touching code. The artifact is the Shared Understanding, and the code is the result of that partnership.
  • Workflow: Context/Approach -> Human Approval -> AI Execution -> Manual Update of Master Plan.

2. Comparative Analysis

Feature Spec Kit (AI-Native SDD) ChatKcal "Plan-First" (Manual)
Primary Artifact The Spec (Markdown). Code is disposable/regeneratable. The Code & The Plan. Docs capture the "Why" and "How".
AI Role Compiler/Factory. Consumes spec, outputs code. Partner/Engineer. Discusses plan, writes code, updates docs.
Human Role Architect/PM. Writes specs, reviews high-level output. Tech Lead. Reviews logic, approves approaches, manages roadmap.
Source of Truth The Markdown Specification. The Codebase + Taskfile + Unit Tests.
Drift Management Re-generate code if spec changes. Manual updates required to keep docs in sync with code.
Granularity fine-grained (Function/Component level). Feature/Task level (Work Logs).

3. Key Differences

"Intent" vs. "History"

  • Spec Kit files are Prescriptive. They say "This component must do X". They are forward-looking.
  • ChatKcal Logs are Narrative. They say "We planned to do X, and here is how we did it". They serve as a historical record of decisions (ADRs).

Verification

  • Spec Kit often pairs with automated validation where the AI writes tests based on the spec to prove compliance.
  • ChatKcal relies on a Layered Testing Strategy (Vitest/RTL) that is part of the codebase, maintained as code, not generated purely from a text spec.

Friction & Overhead

  • Spec Kit: High upfront friction (writing perfect specs). Low execution friction (AI generates everything). Good for greenfield or isolated components.
  • ChatKcal: Moderate friction throughout. Writing the "Approach" takes time, but it catches architectural misalignments early. Better for complex, interconnected systems where "regenerating from spec" is risky.

4. Why We Use "Plan-First" (Manual)

For ChatKcal, the Manual Curation approach is currently superior because:

  1. Complexity Context: We are building on top of existing, complex integrations (AWS Amplify, DynamoDB, React Query). A "Spec" often fails to capture the nuance of existing system constraints that the AI discovers during exploration.
  2. Learning & Control: The goal isn't just "working code"; it's a maintainable codebase that the User understands. The "Approach" phase forces us to explain the implementation strategy, ensuring the User agrees with the design, not just the output.
  3. Flexibility: We can pivot mid-task ("Backtracking") without rewriting a rigid spec. Our tasks.md and logs are living documents that reflect reality, not just intent.

5. Potential Hybrid Evolutions

We could adopt elements of Spec Kit without abandoning our protocol:

  • "Spec" Sections in Work Logs: Make the "Approach" section more formal (e.g., explicitly listing input/output/state) to help the AI generate better code.
  • Validation Prompts: Use the "Verification" section of our log to prompt the AI to write tests specifically asserting the "Approach".