doc-init

Files (5)

• SKILL.md
• config-template.yml · assets/
• new-note.sh · assets/
• refs-claude.md · assets/
• worklog-claude.md · assets/

SKILL.md (first lines)

# Documentation System Init

Set up a low-friction, agent-safe documentation system for this project. Three layers:

- **Worklog** — transient chronological notes, created via a script, auto-named
- **Refs** — curated durable docs (ADRs, PRDs, API refs, domain maps), hand-maintained
- **Summaries** — daily/weekly rollups, written by `/task-workflow:doc-sweep`

The system lives in `.notes-config.yml` at project root plus a `new-note.sh` script. Global skills (`/task-workflow:doc-new-note`, `/task-workflow:doc-sweep`) read the config to behave correctly per project. There are no per-project skill copies.

## Important context

This init is LLM-driven on purpose. A generic scaffold can't know that this particular project already has (for example) `docs/features/inbox/` or a `check-feedback` skill that feeds triage artifacts. Do reconnaissance first. Let what you find inform defaults and integrations. Don't paint a generic tree on top of real existing structure.

## Phase 1 — Reconnaissance

Before asking anything, scan the project. This is quick discovery, not deep analysis.

1. **Already initialized? Be convergent.** If `.notes-config.yml` exists at project root, read it. **Do not bail out.** Instead, recon the project afresh and compute the delta — what's changed since the last init run? Examples:
   - Config says `refs_dir: docs/refs/` but `docs/adr/` now exists with 6 ADRs → propose moving refs_dir.
   - `tasks/` didn't exist at last init but does now → propose wiring task-completion integration.
   - Granularity is `flat` but the worklog now has 140 notes → propose upgrading to `weekly`.
   - A project-local skill was added that produces artifacts → propose wiring it.
   - Worklog script is stale vs the latest `${CLAUDE_PLUGIN_ROOT}/skills/doc-init/assets/new-note.sh` → offer to refresh.

   Present findings and proposed deltas. AskUserQuestion: **Apply changes / Reconfigure from scratch / Nothing to change**. On "nothing to change", exit cleanly. On "from scratch", proceed through the whole flow but preserve existing worklog contents.

2. **Project identity**: dir name, root `CLAUDE.md` if present. Read it — note any existing doc/task conventions or project rules.

3. **Existing doc locations**: check for `docs/`, `notes/`, `research/`, `worklog/`. For each, capture:
   - Subdirectories (e.g. `docs/adr/`, `docs/features/done/`, `docs/architecture/`, `docs/decisions/`, `docs/refs/`, `docs/specs/`) and rough file counts.
   - Any CLAUDE.md files inside.
   - Naming conventions in each subdirectory — are files date-prefixed (transient), numbered like `F001-*`/`ADR-001-*` (durable), or free-form?

   Durable-doc directories (curated, non-transient) are candidates for `refs_dir` — Phase 2 uses this inventory.

4. **Task system**: a bare `tasks/` directory is not enough — it could be runtime state (e.g. Claude Code's task-tool stores UUIDs there). Require *project-task-system* evidence:
   - `tasks/CLAUDE.md` exists, **or**
   - `tasks/global-task-manager.md` / `tasks/GTM.md` / similar, **or**
   - `tasks/active/TXXX-*/main.md` or `tasks/planning/TXXX-*/` pattern, **or**
   - any directly-authored markdown task docs.

   If none of those signals are present (e.g. `tasks/` contains only UUIDs or opaque runtime subdirs), skip task integration entirely and do not mention it in Phase 2 proposals.

5. **Project-local skills**: list `.claude/skills/` (if present). For each skill, read the frontmatter `description` to understand what it does. Pay attention to ones that create artifacts (feedback triage, bug reports, feature specs, incident notes) — these are integration candidates.

6. **Hooks**: glance at `.claude/settings.json` for existing hooks relevant to docs.

7. **Project size/age**: `git log --oneline | wc -l`, first commit date, last commit date. Use to size the system.

8. **Version control**: `test -d .git`. Note if not a git repo.

Present findings to the user in 5-10 lines. Example shape:

> Found:
> - Project: `expenses-app` — 3 months old, 187 commits
> - Docs: `docs/features/inbox/` (existing feature spec system)
> - Tasks: none
> - Local skills: `check-feedback` (triages voice feedback from the mobile app)
> - Hooks: none relevant
>
> Proposed setup:
> - Worklog at `docs/worklog/` alongside existing `docs/features/`
> - Daily granularity, daily summaries
> - Refs at `docs/refs/` for future ADRs
> - Integration: `check-feedback` could append triage notes to today's worklog
>
> Proceed with defaults, customise, or architect?

## Phase 2 — Propose a shape

Default rules (use unless recon suggests otherwise):

**Worklog location**: reuse existing `docs/` if present; otherwise create `docs/worklog/`. Never collide with existing content.

**Refs location**: detect existing durable-doc directories before creating a new one.

- Scan `docs/` for subdirectories containing ≥3 markdown files that are **not** date-prefixed (i.e. curated, not transient). Candidates include `docs/adr/`, `docs/architecture/`, `docs/decisions/`, `docs/features/done/`, `docs/refs/`, `docs/specs/`.
- **One match** → propose it as `refs_dir`. Don't create a parallel empty `docs/refs/`.
- **Multiple matches** → ask which (or store multiple, comma-separated, if the user wants).
- **No matches** → default to `docs/refs/`. Skip entirely if the project is <1 month old and has no durable docs yet.

**Granularity**:
- <1 month old, <50 commits → `flat`
- 1-6 months → `daily`
- 6+ months or 500+ commits → `weekly`

**Summary cadence**:
- `flat` → `none` (project is small enough that git log + STATUS.md suffice)
- `daily` → `daily`
- `weekly` → `daily+weekly`

Cadence options: `none` / `daily` / `weekly` / `daily+weekly`. `weekly`-only is for long-running projects with modest daily volume — `/task-workflow:doc-sweep` runs at week-end (Friday or Sunday) and rolls up the week without daily summaries.

**Integrations**: propose one per genuinely relevant existing artifact producer you found in recon. Don't invent integrations — only propose wiring for things you actually saw.

Use `AskUserQuestion` with three choices: Quick Start / Customise / Architect.

## Phase 3 — Interview (level-gated)

### Quick Start
No questions. You already confirmed with them in Phase 2. Go to Phase 4.

### Customise
Batch into a single `AskUserQuestion` call (skip any already answered by recon):

1. Worklog directory (free text, default from recon)
2. Granularity — `flat` / `daily` / `weekly`
3. Summary cadence — `none` / `daily` / `weekly` / `daily+weekly`
4. Include refs directory (`yes` / `no`)
5. If `tasks/` exists: wire task-completion notes (`yes` / `no`)

### Architect
All Customise questions, plus:

- Template overrides (custom headings for note / summary / weekly-summary)
- Hooks via `update-config` skill — e.g. on-stop reminder to sweep, on-task-complete note creation
- Integrations list — confirm each one you proposed and allow the user to reject or add
- `week_style` (iso is the only supported value for now; note if the user wants engagement-relative weeks so it can be added later)

From blakesims/task-workflow-plugin, MIT.

More from blakesims/task-workflow-plugin