cai-add-spec

CAI Add Spec

Overview

Creates a new spec or updates an existing spec document, then validates it against source code via the verification agent.

When to Use

• AI proposes spec creation after modifying a previously undocumented area
• AI proposes spec update after code changes diverge from existing spec
• User explicitly requests a spec for a file, module, or component
• Action routing: "spec 생성/수정 필요" triggers this skill

Workflow

1. Determine Target

Identify the target file(s) or module to document. Resolve to a spec path using convention-based mapping:

• Module-level: context/specs/{module}/_overview.md
• Component-level: context/specs/{module}/{component}.md

If the target, scope, or intent is ambiguous (e.g., the user said "add a spec for auth" but the auth area spans multiple modules, or it is unclear which behaviors should be documented), invoke the cai:cai-interview skill before proceeding. Pass:

• Goal: Clarify spec scope and intent.
• What is already known: The candidate target paths and any existing specs nearby.
• Output target: This skill's working memory — answers will shape Step 2 onward, not a file directly.
• Seed questions: Which files/modules to cover; module vs. component level; any behaviors to emphasize or exclude.

Skip the interview when the target is unambiguous.

2. Check Existing Spec

Does a spec already exist for this target?
├── YES → Update Mode (Step 3a)
└── NO  → Create Mode (Step 3b)

3a. Update Mode (Diff-Based)

1. Read the existing spec
2. Read the current source code for the covered area
3. Identify differences between spec and code
4. Invoke the spec-writer agent with update instructions:
   • Provide the existing spec content
   • Provide a summary of code changes since last_synced
   • Instruct to update only the changed sections
5. Proceed to Step 4

3b. Create Mode

1. Determine spec level (module or component)
2. Determine parent spec (if component-level, parent is the module's _overview.md)
3. Invoke the spec-writer agent with creation instructions:
   • Provide the source file paths to cover
   • Provide the target spec path
   • Instruct to generate a complete spec with frontmatter conforming to Interface Contract 0.1
4. Proceed to Step 4

4. Verification (MANDATORY)

Invoke the verification-agent to cross-validate the new or updated spec against source code.

Verification passed?
├── YES → Step 5
└── NO  → Present issues to user. Options:
    ├── Fix and re-verify
    └── Accept with noted discrepancies (mark confidence: draft)

5. Finalize

1. Write the spec file to its target path
2. Update last_synced to today's date (ISO 8601: YYYY-MM-DD)
3. Apply verification-agent's recommended confidence level:
   • All claims confirmed → verified
   • Mostly confirmed (≥80%), 0 incorrect → reviewed
   • Any incorrect claims → draft
4. If component-level, ensure parent module's _overview.md lists this component in components field
5. Report completion to user

Agent Invocations

• Agent: spec-writer — Reads source code and writes spec documents

  • Create: Task("Create a new {level}-level spec for {target_path}. Source files: {file_list}. Write to: {spec_path}. Follow frontmatter schema from interface contract.", agent="agents/spec-writer.md")
  • Update: Task("Update spec at {spec_path}. Current spec: {spec_content}. Changes since last sync: {change_summary}. Update only changed sections.", agent="agents/spec-writer.md")

• Agent: verification-agent — Validates spec claims against source code

  • Invocation: Task("Verify spec at {spec_path} against source code. Check all claims for accuracy.", agent="agents/verification-agent.md")

Output

Artifact	Path	Format
New/updated spec	context/specs/{module}/_overview.md or context/specs/{module}/{component}.md	Markdown with YAML frontmatter (Interface Contract 0.1)

Frontmatter example (new spec):

---
type: spec
level: module
tags: [auth, security]
last_synced: 2026-04-06
covers: [src/auth/]
confidence: draft
components: [login, refresh, oauth]
exports: [authenticate, refreshToken]
depends_on: [context/specs/database/_overview.md]
---

Error Handling

Error	Action
spec-writer produces empty or malformed output	Retry once. If still fails, report error and ask user to provide manual input.
verification-agent finds critical inaccuracies	Do NOT finalize. Present the inaccuracy report. Ask user to choose: fix or accept as draft.
Target module cannot be determined	Ask user to specify the module/component path explicitly.
Parent overview does not exist (component spec)	Create a minimal parent _overview.md first, then proceed.