docs-ssot general.instructions.md

General Development Rules for docs-ssot

Project Purpose

docs-ssot is a CLI tool that generates documentation files (README.md, CLAUDE.md, AGENTS.md) from modular Markdown source files using a template-based composition system. It implements the Single Source of Truth (SSOT) principle for documentation.

---

Critical Rule: Never Edit Generated Files

The following files are build artifacts — do NOT edit them directly:

• README.md
• CLAUDE.md
• AGENTS.md

Always edit the source files in docs/ and regenerate with make docs.

---

Repository Structure

docs-ssot/
├── cmd/docs-ssot/main.go       # CLI entry point (build command)
├── internal/
│   ├── config/config.go        # YAML config loader (Config, Target types)
│   ├── generator/generator.go  # Build orchestrator (Build func)
│   └── processor/              # Include resolver + transformer pipeline (ProcessFile func)
├── docs/                       # Source Markdown files (SSOT — edit here)
│   ├── 01_project/             # Project context and vision
│   ├── 02_product/             # Product concept and features
│   ├── 03_architecture/        # System architecture and pipeline
│   ├── 04_development/         # Setup, testing, linting guides
│   ├── 05_ai/                  # AI tool-specific docs (Claude, Cursor, Codex, etc.)
│   └── 06_reference/           # Commands and directory reference
├── template/                   # Document templates (define output structure)
│   ├── README.tpl.md
│   ├── CLAUDE.tpl.md
│   └── AGENTS.tpl.md
├── docsgen.yaml                # Build targets: template → output mapping
├── Makefile                    # Build, lint, test, docs commands
└── .golangci.yml               # Linting configuration (46+ linters)

---

Go Package Responsibilities

Package	File	Responsibility
main	cmd/docs-ssot/main.go	CLI arg parsing, dispatch to generator.Build()
config	internal/config/config.go	Load/save docsgen.yaml into Config{Targets []Target}
generator	internal/generator/generator.go	Iterate targets, call include resolver, write output
processor	internal/processor/processor.go	Include resolution, transformer pipeline (ProcessFile, Transformer, Apply)
agentscan	internal/agentscan/agentscan.go	Detect AI tools (.claude/, .cursor/, .github/, .codex/) and collect agent files
frontmatter	internal/frontmatter/frontmatter.go	Parse/strip/generate YAML frontmatter for different tool formats
migrate	internal/migrate/agents.go	Agent-aware migration pipeline (scan → section → template → config → verify)