project-wiki-specify

name	project-wiki-specify
version	1.0.0
description	This skill should be used when the user wants to add a specified topic to the Project Wiki. It generates a focused wiki article on a user-provided theme (e.g., "explore how X feature works", "research why X technology was chosen"), placing it in a dedicated Specify Wiki section separate from Getting Started and Deep Dive.

Project Wiki Specify Skill

This skill guides a Code Agent to add a specified topic to an existing Project Wiki. The user provides a topic or question; the agent generates a focused, research-grade article and places it in the Specify Wiki section (separate from Getting Started and Deep Dive).

Prerequisites

1. An existing wiki must exist at ./.atmos/wiki/ with a valid _catalog.json.
2. Read these shared references from project-wiki (installed at ~/.atmos/skills/.system/project-wiki/) before making any changes:
   • Content & formatting: ~/.atmos/skills/.system/project-wiki/references/output_structure.md
   • Research briefing template: ~/.atmos/skills/.system/project-wiki/references/briefing_template.md
   • Sample briefing: ~/.atmos/skills/.system/project-wiki/examples/sample_briefing.md
   • Catalog schema: ~/.atmos/skills/.system/project-wiki/references/catalog.schema.json

The generated article MUST meet specify-wiki content depth requirements: 1500+ words, 3+ Mermaid diagrams, 6+ H2 sections, 5+ source files, 4+ cross-references. Run ~/.atmos/skills/.system/project-wiki/scripts/validate_content.py to verify.

Input Context

The user prompt will provide:

• topic: A string describing what wiki article to generate. Examples (user replaces bracketed parts for their project):
  • "Explore how [feature name] is implemented"
  • "Research why the project chose [technology] for [purpose]"
  • "Understand how [module/component] works"
  • "Document the [mechanism/flow] design"
  • "Explain the design decision behind [architecture choice]"

Workflow

Step 1: Ensure Specify Wiki Section Exists

1. Read _catalog.json.
2. If no top-level section with id: "specify-wiki" exists, create it:
   • Add a catalog item: { "id": "specify-wiki", "title": "Specify Wiki", "path": "specify-wiki", "order": 2, "file": "specify-wiki/index.md", "section": "specify-wiki", "level": "intermediate", "children": [] }
   • Create the directory ./.atmos/wiki/specify-wiki/.
   • Create specify-wiki/index.md as an index/overview for the Specify Wiki section if missing.

Step 2: Research the Topic

1. Read metadata (if available): _metadata/commit_details.txt, _concepts.json — use these to understand evolution and existing concepts.
2. Deep-dive into the codebase to answer the user's topic/question.
3. Identify the relevant source files (at least 5 for specify-wiki).
4. Understand the implementation, design decisions, and data flow.
5. Extract relevant Git history and PR/Issue context for "why" and "how it evolved".

Step 3: Create Research Briefing

Before writing the article, create a research briefing at ./.atmos/wiki/_briefings/specify-wiki/{topic-slug}.md (e.g. _briefings/specify-wiki/wiki-implementation.md). Use ~/.atmos/skills/.system/project-wiki/references/briefing_template.md as template. Include:

• Involved concepts (from _concepts.json or newly identified)
• Must-answer research questions (e.g. "Why was this approach chosen?", "How does it integrate with X?")
• Required source files and why each matters

Step 4: Generate the Article (Research-Type)

1. Act as a technical researcher, not a document summarizer. Answer every research question from the briefing.
2. Create a new Markdown file under ./.atmos/wiki/specify-wiki/ using kebab-case (e.g., websocket-lifecycle.md, why-rust-backend.md).
3. Follow project-wiki conventions:
   • YAML frontmatter: title, section: "specify-wiki", level, reading_time, path, sources (array, 5+), updated_at
   • Minimum 1500 words — expand by covering design decisions, evolution, and edge cases
   • 3+ Mermaid diagrams, 6+ H2 sections
   • Required sections: Introduction, Overview, Architecture, Design Decisions / Error Handling / Evolution (as relevant), Key Source Files, Next Steps (4+ cross-reference links)
4. Add the new article to _catalog.json under the specify-wiki section with correct order.

Step 5: Update Catalog and Validate

1. Update _catalog.json with the new catalog entry.
2. Run all validation scripts from project-wiki. All must pass:

   python3 ~/.atmos/skills/.system/project-wiki/scripts/validate_catalog.py .atmos/wiki/_catalog.json
   python3 ~/.atmos/skills/.system/project-wiki/scripts/validate_frontmatter.py .atmos/wiki/
   python3 ~/.atmos/skills/.system/project-wiki/scripts/validate_content.py .atmos/wiki/
   

3. If validate_content fails for the new article, expand the content until it passes.

Alignment with project-wiki

All generated content MUST follow the same conventions as the full project-wiki skill:

• Same frontmatter schema (with section: "specify-wiki")
• Same content style (prose-first, minimal code, prefer Mermaid)
• Same content depth — specify-wiki uses Deep Dive thresholds: 1500+ words, 3+ diagrams, 6+ H2s, 5+ sources, 4+ cross-refs; must pass validate_content
• Same file naming (kebab-case under .atmos/wiki/specify-wiki/)
• Same catalog item structure (id, title, path, order, file, section, level, reading_time, children)
• Research-type Agent role — explain why and how it evolved, not just what

Edge Cases

• Topic too broad: Suggest a more focused topic or split into multiple articles.
• Topic not applicable: If the codebase has no relevant code, explain that to the user and suggest an alternative.
• Duplicate content: If a similar article already exists, consider updating it instead of creating a duplicate.
• Shallow output: If the first draft is under 1500 words, expand by adding Design Decisions, Error Handling, Evolution, or Configuration sections — do not consider the article complete until validate_content passes.