The doc-torn project empowers AI coding agents to maintain structured documentation in sync with the code. By implementing a clear hierarchy and a comprehensive dependency matrix, it enhances code understanding and documentation consistency. Ideal for teams looking to streamline their development processes.
doc-torn is a project designed to enhance the documentation skills of AI coding agents, ensuring that documentation is consistently structured and in sync with the corresponding code. This repository establishes a hierarchical documentation framework (L0 → L1 → L2 → L3) along with a clear dependency matrix among various features.
Key Skills
- Structured Documentation: Manages the core lifecycle from initialization to updates, adhering to the L0-L3 hierarchy.
- Doc-Driven Exploration: Promotes a documentation-first approach, encouraging thorough reading of documents before engaging with the code.
- Documentation Consistency: Conducts comprehensive audits of all documentation against the codebase, with capabilities to auto-fix discrepancies.
Tool Overview
- doc-torn-scan: A Go binary tool that enables iterative documentation processes on a feature-by-feature basis. It is utilized for tree scanning, scaffold generation, and meta-document creation.
Usage
The capabilities of doc-torn are leveraged based on specific tasks:
| Task | Load Skill | Follow-up Action |
|---|---|---|
| Documenting a new codebase | structured-documentation (init mode) | Engages in the doc-torn-scan workflow iteratively |
| Preparing for a new feature implementation | doc-driven-exploration | Reviews existing documentation before code engagement |
| Finalizing documentation post-feature completion | structured-documentation (update mode) | Synchronizes documentation, recalculates dependencies, and updates AGENTS.md |
| Regular audits or pre-release checks | documentation-consistency | Conducts thorough audits and auto-fixes discrepancies |
Documentation Hierarchy (L0 → L3)
The project adopts a structured documentation hierarchy that separates concerns by abstraction level, facilitating a tailored reading experience for different stakeholders:
| Level | File | Reader Type | Purpose |
|---|---|---|---|
| L0 | docs/README.md | General Audience | Provides an overview, architecture diagram, and feature list. |
| L1 | docs/features/<name>/README.md | Feature Developers | Details feature objectives, logic, dependencies, APIs, and key files. |
| L2 | docs/features/<name>/sub-features/*.md | Implementers | Contains details on edge cases, business rules, and sub-flows. |
| L3 | docs/features/<name>/implementation/*.md | Maintainers | Discusses technical decisions, rationale, and trade-offs. |
This layered approach ensures that users can access only the information pertinent to their role, from high-level overviews to in-depth analyses.
Repository Structure
The following structure is maintained:
skills/
structured-documentation/
doc-driven-exploration/
documentation-consistency/
tools/
doc-torn-scan/
examples/
AGENTS.md
hooks/
Overall, doc-torn equips AI coding agents with the essential skills for maintaining high-quality, accurate documentation that evolves with the development lifecycle, streamlining the programming workflow and enhancing collaboration.
No comments yet.
Sign in to be the first to comment.