# focus695/bocode architecture

> Architecture diagram of the GitHub repository focus695/bocode, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/focus695/bocode
- Repository: https://github.com/focus695/bocode

## Overview

BoCode is a project template for human-and-agent software development: code is the executable truth, while the book is the navigable knowledge base. The principal cycle is to consult plans, guidelines, experience, and issues; pass through gated requirements, analysis, design approval, implementation, testing, review, and wrap-up; then write summaries, lessons, issues, changelogs, and an updated index back to the book. The graph reflects README-documented behavior; sampled source confirms the index generator and commit validator, but does not expose skill internals.

Main entry points: [`code`](https://github.com/focus695/bocode/tree/dev/code) (Implementation), [`book/guidelines/workflow.md`](https://github.com/focus695/bocode/blob/dev/book/guidelines/workflow.md) (Wrap-up), [`book/notes`](https://github.com/focus695/bocode/tree/dev/book/notes) (Running records), [`book/README.md`](https://github.com/focus695/bocode/blob/dev/book/README.md) (Book index)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Gated workflow"]
  node_requirements["Requirements brief<br/>[workflow.md]"]
  node_analysis["Analysis<br/>[workflow.md]"]
  node_design["Design approval<br/>[workflow.md]"]
  node_implementation["Implementation"]
  node_testing["Testing<br/>[workflow.md]"]
  node_review["Review<br/>[workflow.md]"]
  node_wrapup["Wrap-up<br/>[workflow.md]"]
end

subgraph group_knowledge["Project knowledge"]
  node_book["Knowledge base"]
  node_plans["Plans"]
  node_guidelines["Guidelines"]
  node_running_records["Running records"]
  node_book_index["Book index<br/>[README.md]"]
end

subgraph group_skills["Agent skills"]
  node_bocode["Session discipline<br/>[SKILL.md]"]
  node_boscope["Scope gates<br/>[SKILL.md]"]
  node_writeback["Book write-back<br/>[SKILL.md]"]
  node_bowrite["Writing discipline<br/>[SKILL.md]"]
end

subgraph group_runtime["Template tooling"]
  node_index_generator["Index generator<br/>[gen-book-index.mjs]"]
  node_commit_policy["Commit validator"]
end

node_human(("Human"))
node_agent(("AI agent"))

node_human -->|"sets scope"| node_requirements
node_agent -->|"fills brief"| node_requirements
node_requirements -->|"gates"| node_analysis
node_analysis -->|"informs"| node_design
node_human -->|"approves"| node_design
node_design -->|"authorizes"| node_implementation
node_implementation -->|"proceeds to"| node_testing
node_testing -->|"proceeds to"| node_review
node_review -->|"records findings"| node_wrapup
node_book -->|"drives"| node_implementation
node_plans -->|"guides"| node_implementation
node_guidelines -->|"sets baseline"| node_implementation
node_running_records -->|"provides context"| node_implementation
node_wrapup -->|"writes back"| node_running_records
node_wrapup -->|"regenerates"| node_book_index
node_agent -->|"invokes"| node_bocode
node_agent -->|"invokes"| node_boscope
node_agent -->|"invokes"| node_writeback
node_agent -->|"invokes"| node_bowrite
node_index_generator -->|"generates"| node_book_index
node_commit_policy -->|"validates subjects"| node_human

click node_requirements "https://github.com/focus695/bocode/blob/dev/book/guidelines/workflow.md"
click node_analysis "https://github.com/focus695/bocode/blob/dev/book/guidelines/workflow.md"
click node_design "https://github.com/focus695/bocode/blob/dev/book/guidelines/workflow.md"
click node_implementation "https://github.com/focus695/bocode/tree/dev/code"
click node_testing "https://github.com/focus695/bocode/blob/dev/book/guidelines/workflow.md"
click node_review "https://github.com/focus695/bocode/blob/dev/book/guidelines/workflow.md"
click node_wrapup "https://github.com/focus695/bocode/blob/dev/book/guidelines/workflow.md"
click node_book "https://github.com/focus695/bocode/tree/dev/book"
click node_plans "https://github.com/focus695/bocode/tree/dev/book/plans"
click node_guidelines "https://github.com/focus695/bocode/tree/dev/book/guidelines"
click node_running_records "https://github.com/focus695/bocode/tree/dev/book/notes"
click node_book_index "https://github.com/focus695/bocode/blob/dev/book/README.md"
click node_bocode "https://github.com/focus695/bocode/blob/dev/skills/bocode/SKILL.md"
click node_boscope "https://github.com/focus695/bocode/blob/dev/skills/boscope/SKILL.md"
click node_writeback "https://github.com/focus695/bocode/blob/dev/skills/book-writeback/SKILL.md"
click node_bowrite "https://github.com/focus695/bocode/blob/dev/skills/bowrite/SKILL.md"
click node_index_generator "https://github.com/focus695/bocode/blob/dev/code/tools/gen-book-index.mjs"
click node_commit_policy "https://github.com/focus695/bocode/blob/dev/scripts/check-commit-message.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_requirements,node_analysis,node_design,node_implementation,node_testing,node_review,node_wrapup toneBlue
class node_book,node_plans,node_guidelines,node_running_records,node_book_index toneAmber
class node_bocode,node_boscope,node_writeback,node_bowrite toneMint
class node_index_generator,node_commit_policy toneRose
class node_human,node_agent toneIndigo
```

## Components

### Gated workflow

- [Requirements brief](https://github.com/focus695/bocode/blob/dev/book/guidelines/workflow.md): `book/guidelines/workflow.md`
- [Analysis](https://github.com/focus695/bocode/blob/dev/book/guidelines/workflow.md): `book/guidelines/workflow.md`
- [Design approval](https://github.com/focus695/bocode/blob/dev/book/guidelines/workflow.md): `book/guidelines/workflow.md`
- [Implementation](https://github.com/focus695/bocode/tree/dev/code): `code`
- [Testing](https://github.com/focus695/bocode/blob/dev/book/guidelines/workflow.md): `book/guidelines/workflow.md`
- [Review](https://github.com/focus695/bocode/blob/dev/book/guidelines/workflow.md): `book/guidelines/workflow.md`
- [Wrap-up](https://github.com/focus695/bocode/blob/dev/book/guidelines/workflow.md): `book/guidelines/workflow.md`

### Project knowledge

- [Knowledge base](https://github.com/focus695/bocode/tree/dev/book): `book`
- [Plans](https://github.com/focus695/bocode/tree/dev/book/plans): `book/plans`
- [Guidelines](https://github.com/focus695/bocode/tree/dev/book/guidelines): `book/guidelines`
- [Running records](https://github.com/focus695/bocode/tree/dev/book/notes): `book/notes`
- [Book index](https://github.com/focus695/bocode/blob/dev/book/README.md): `book/README.md`

### Agent skills

- [Session discipline](https://github.com/focus695/bocode/blob/dev/skills/bocode/SKILL.md): `skills/bocode/SKILL.md`
- [Scope gates](https://github.com/focus695/bocode/blob/dev/skills/boscope/SKILL.md): `skills/boscope/SKILL.md`
- [Book write-back](https://github.com/focus695/bocode/blob/dev/skills/book-writeback/SKILL.md): `skills/book-writeback/SKILL.md`
- [Writing discipline](https://github.com/focus695/bocode/blob/dev/skills/bowrite/SKILL.md): `skills/bowrite/SKILL.md`

### Template tooling

- [Index generator](https://github.com/focus695/bocode/blob/dev/code/tools/gen-book-index.mjs): `code/tools/gen-book-index.mjs`
- [Commit validator](https://github.com/focus695/bocode/blob/dev/scripts/check-commit-message.mjs): `scripts/check-commit-message.mjs`

### Other components

- **Human**
- **AI agent**

## Connections

- Human → Requirements brief: sets scope (evidence: `README.md`)
- AI agent → Requirements brief: fills brief (evidence: `README.md`)
- Requirements brief → Analysis: gates (evidence: `README.md`)
- Analysis → Design approval: informs (evidence: `README.md`)
- Human → Design approval: approves (evidence: `README.md`)
- Design approval → Implementation: authorizes (evidence: `README.md`)
- Implementation → Testing: proceeds to (evidence: `README.md`)
- Testing → Review: proceeds to (evidence: `README.md`)
- Review → Wrap-up: records findings (evidence: `README.md`)
- Knowledge base → Implementation: drives (evidence: `README.md`)
- Plans → Implementation: guides (evidence: `README.md`)
- Guidelines → Implementation: sets baseline (evidence: `README.md`)
- Running records → Implementation: provides context (evidence: `README.md`)
- Wrap-up → Running records: writes back (evidence: `README.md`)
- Wrap-up → Book index: regenerates (evidence: `README.md`)
- AI agent → Session discipline: invokes (evidence: `README.md`)
- AI agent → Scope gates: invokes (evidence: `README.md`)
- AI agent → Book write-back: invokes (evidence: `README.md`)
- AI agent → Writing discipline: invokes (evidence: `README.md`)
- Index generator → Book index: generates (evidence: `code/tools/gen-book-index.mjs`)
- Commit validator → Human: validates subjects (evidence: `scripts/check-commit-message.mjs`)
