# docs-framework

Adopt this skill: https://proskills.md/skills/other/dean0x-devflow-src-assets-skills-docs-framework

Page: https://proskills.md/skills/other/dean0x-devflow-src-assets-skills-docs-framework
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: src/assets/skills/docs-framework/SKILL.md
size: 8298
upstream: https://github.com/dean0x/devflow/blob/main/src/assets/skills/docs-framework/SKILL.md

````text
---
name: docs-framework
description: This skill should be used when the user asks to "create a review report", "write a status log", "add documentation", "name this artifact", or creates files in the .devflow/docs/ directory. Provides naming conventions, templates, and directory structure for reviews, debug sessions, design docs, and all persistent Devflow documentation artifacts.
user-invocable: false
allowed-tools: Read, Bash, Glob
---

# Documentation Framework

The canonical source for documentation conventions in Devflow. All agents that persist artifacts must follow these standards.

## Iron Law

> **ALL ARTIFACTS FOLLOW NAMING CONVENTIONS**
>
> Timestamps are `YYYY-MM-DD_HHMM`. Branch slugs replace `/` with `-`. Topic slugs are
> lowercase alphanumeric with dashes. No exceptions. Inconsistent naming breaks tooling,
> searching, and automation. Follow the pattern or fix the pattern for everyone.

---

## Directory Structure

All generated documentation lives under `.devflow/docs/` in the project root:

```
.devflow/docs/
├── reviews/{branch-slug}/              # Code review reports per branch
│   ├── .last-review-head              # HEAD SHA of last completed review (for incremental)
│   ├── {timestamp}/                   # Timestamped review directory (YYYY-MM-DD_HHMM)
│   │   ├── {focus}.md                 # Review agent report (e.g., security.md, architecture.md)
│   │   ├── review-summary.md          # Synthesize agent output
│   │   └── resolution-summary.md      # Written by /resolve (if run)
│   └── {timestamp}/                   # Second review (incremental)
│       ├── {focus}.md
│       └── review-summary.md
├── bug-analysis/{branch-slug}/          # Bug analysis reports per branch
│   ├── .last-analysis-head            # HEAD SHA of last analysis (for incremental)
│   └── {timestamp}/                   # Timestamped analysis directory (YYYY-MM-DD_HHMM)
│       ├── {focus}.md                 # Analyzer report (e.g., security.md, functional.md)
│       ├── static-findings.md         # Raw static analysis tool output
│       ├── bug-analysis-summary.md    # Synthesize agent output
│       └── resolution-summary.md      # Written by /resolve (if run)
├── design/                             # Design artifacts from /plan
│   └── {ISSUE_ID}-{topic-slug}.{timestamp}.md  # Design document
├── tickets/{slug}/                     # Ticket sets from /dynamic-tickets
│   └── {YYYY-MM-DD_HHMM}/             # Timestamped ticket directory
│       ├── {ticket-slug}.md            # Individual ticket files
│       └── tracking-issue.md           # Tracking issue body (GitHub sync)
├── waves/{slug}/                       # Wave run reports from /dynamic-build
│   └── {YYYY-MM-DD_HHMM}/             # Timestamped wave directory
│       └── wave-report.md              # Wave run summary and status
├── research/{topic-slug}/              # Research artifacts per topic
│   └── {YYYY-MM-DD_HHMM}/             # Timestamped research directory
│       ├── {type}.md                  # Research agent outputs (codebase.md, external.md, etc.)
│       └── research-summary.md        # Synthesize agent output
├── status/                             # Development logs
│   ├── {timestamp}.md
│   ├── compact/{timestamp}.md
│   └── INDEX.md
└── swarm/                              # Swarm operation state
    ├── state.json
    └── plans/

.devflow/memory/
├── WORKING-MEMORY.md                   # Auto-maintained by Stop hook (overwritten)
└── backup.json                         # Pre-compact git state snapshot

.devflow/learning/
├── decisions.md                        # Architectural decisions (ADR-NNN format)
└── pitfalls.md                         # Known pitfalls (PF-NNN format)
```

`{ISSUE_ID}` in the `design/` path is the filesystem-safe issue identifier the Git agent emits as `- **Issue ID**:` under `### Handoff Values`.

---

## Naming Conventions

### Timestamps
Format: `YYYY-MM-DD_HHMM` (sortable, readable)
```bash
TIMESTAMP=$(date +%Y-%m-%d_%H%M)  # Example: 2025-12-26_1430
```

### Branch Slugs
Replace `/` with `-`, sanitize special characters:
```bash
BRANCH_SLUG=$(git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "standalone")
```

### Topic Slugs
Lowercase, dashes, alphanumeric only, max 50 chars:
```bash
TOPIC_SLUG=$(echo "$TOPIC" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^a-z0-9-]//g' | cut -c1-50)
```

### File Naming Patterns

| Type | Pattern | Example |
|------|---------|---------|
| Special indexes | `UPPERCASE.md` | `WORKING-MEMORY.md`, `INDEX.md` |
| Review reports | `{focus}.md` in timestamped dir | `2025-12-26_1430/security.md` |
| Review summary | `review-summary.md` in timestamped dir | `2025-12-26_1430/review-summary.md` |
| Resolution summary | `resolution-summary.md` in timestamped dir | `2025-12-26_1430/resolution-summary.md` |
| Review head marker | `.last-review-head` | Plain text file with SHA |
| Status logs | `{timestamp}.md` | `2025-12-26_1430.md` |
| Design documents | `{ISSUE_ID}-{topic-slug}.{timestamp}.md` | `42-jwt-auth.2026-04-07_1430.md` |
| Research outputs | `{type}.md` in timestamped dir | `2025-12-26_1430/codebase.md` |
| Research summary | `research-summary.md` in timestamped dir | `2025-12-26_1430/research-summary.md` |
| Bug analysis reports | `{focus}.md` in timestamped dir | `2025-12-26_1430/security.md` |
| Bug analysis summary | `bug-analysis-summary.md` in timestamped dir | `2025-12-26_1430/bug-analysis-summary.md` |
| Static findings | `static-findings.md` in timestamped dir | `2025-12-26_1430/static-findings.md` |
| Analysis head marker | `.last-analysis-head` | Plain text file with SHA |

---

## Helper Functions

Define these inline, in the Bash call that needs them, for consistent naming. `.devflow/docs/` lives at the checkout's toplevel, never under a subdirectory the session started in:

```bash
get_timestamp() { date +%Y-%m-%d_%H%M; }
get_branch_slug() { git branch --show-current 2>/dev/null | sed 's/\//-/g' || echo "standalone"; }
get_topic_slug() { echo "$1" | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | sed 's/[^a-z0-9-]//g' | cut -c1-50; }
get_docs_root() { git rev-parse --show-toplevel 2>/dev/null || pwd; }
ensure_docs_dir() { mkdir -p "$(get_docs_root)/.devflow/docs/$1"; }
```

---

## Agent Persistence Rules

### Agents That Persist Artifacts

| Agent | Output Location | Behavior |
|-------|-----------------|----------|
| Review agent | `.devflow/docs/reviews/{branch-slug}/{timestamp}/{focus}.md` | Creates new in timestamped dir |
| Synthesize agent (review) | `.devflow/docs/reviews/{branch-slug}/{timestamp}/review-summary.md` | Creates new in timestamped dir |
| Resolve cmd | `.devflow/docs/reviews/{branch-slug}/{timestamp}/resolution-summary.md` | Written by /resolve orchestrator (Phase 5) |
| Code-review cmd | `.devflow/docs/reviews/{branch-slug}/.last-review-head` | Overwrites with HEAD SHA |
| Working Memory | `.devflow/memory/WORKING-MEMORY.md` | Overwrites (auto-maintained by Stop hook) |
| Decisions | `.devflow/learning/decisions.md` | Rendered from `decisions-ledger.jsonl` (active ADR-NNN rows; retired rows dropped) |
| Pitfalls | `.devflow/learning/pitfalls.md` | Rendered from `decisions-ledger.jsonl` (active PF-NNN rows; retired rows dropped) |
| Design agent (via /plan) | `.devflow/docs/design/{ISSUE_ID}-{topic-slug}.{timestamp}.md` | Creates new design artifact |
| Research agent | `.devflow/docs/research/{topic-slug}/{timestamp}/{type}.md` | Creates new in timestamped dir |
| Synthesize agent (research) | `.devflow/docs/research/{topic-slug}/{timestamp}/research-summary.md` | Creates new in timestamped dir |
| Diagnose agent | `.devflow/docs/bug-analysis/{branch-slug}/{timestamp}/{focus}.md` | Creates new in timestamped dir |
| Synthesize agent (bug-analysis) | `.devflow/docs/bug-analysis/{branch-slug}/{timestamp}/bug-analysis-summary.md` | Creates new in timestamped dir |
| Bug-analysis cmd | `.devflow/docs/bug-analysis/{branch-slug}/.last-analysis-head` | Overwrit
````

## File: README.md
upstream: https://github.com/dean0x/devflow/blob/main/README.md

````text
# Devflow

[![npm version](https://img.shields.io/npm/v/devflow-kit)](https://www.npmjs.com/package/devflow-kit)
[![CI](https://github.com/dean0x/devflow/actions/workflows/ci.yml/badge.svg)](https://github.com/dean0x/devflow/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/dean0x/devflow/blob/main/LICENSE)
[![Node.js 22+](https://img.shields.io/badge/node-22%2B-brightgreen.svg)](https://nodejs.org/)
[![Website](https://img.shields.io/badge/Website-dean0x.github.io%2Fx%2Fdevflow-blue)](https://dean0x.github.io/x/devflow/)

**A meta-harness for Claude Code.** Claude Code gives you one brilliant engineer. Devflow installs the engineering organization around it: an orchestrator that delegates, a roster of specialized agents, a review culture, institutional memory, and a delivery pipeline. Built for developers turning agentic development into a team that ships.

## The problem with AI-assisted development

Claude Code is powerful. But a single agent is not a team. Every session starts from scratch, context evaporates between conversations, reviews are single-pass and shallow, and quality depends on what you remember to ask for. What's missing is exactly what makes an engineering team ship: memory, standards, review culture, and a delivery process.

Devflow fixes this. Install once, forget about it.

## See it work

One feature, four commands, bird's-eye view — each command is an agent pipeline, not a prompt:

```text
you: /plan add rate limiting to the /api/upload endpoint

  Skim · Explore         orient in the codebase (at depth normal) — relevant modules, existing middleware patterns
  Design                 gap analysis: completeness, security, performance
  Plan · Synthesize      PR-ready plan document → .devflow/docs/design/
  Git                    traceable issue #42 opened

you: /implement (hand it the plan)

  Git                    branch feat/42-rate-limit-upload
  Code                   implements the plan — your learned decisions, pitfalls, and feature knowledge preloaded
  Polish · Harden        cleanup pass at full, then 9-pillar quality gate (lean: not on docs-only diffs)
  Evaluate               implementation matches the original request ✓ (standard, lean: checked once)
  Validate               build ✓ typecheck ✓ lint ✓ tests ✓
  Test                   5/5 QA scenarios pass
  Git                    PR opened → CI green ✓

you: /code-review

  Review ×12             security, architecture, performance, complexity, … (up to 20, in parallel)
  Synthesize             18 findings ranked by severity + confidence → review-summary.md

you: /resolve

  Triage                 every finding validated against a blast-radius matrix — 11 fix-now, 3 by design, 4 false positives
  Code ×11               each real issue fixed
  Validate · Git         verification gate ✓ → pushed to the PR
```

This is the **orchestrated flow** — you stay in the loop between every step. With ambient mode on you don't even need the commands: describe the task and the orchestrator routes it through the same pipelines.

## What you get

**Ambient orchestration.** Your main session becomes the tech lead: a charter injected at session start turns it into an orchestrator that delegates work to specialized agents and keeps judgment mainline, with one bounded inline exception for a single short git, gh or script command. Init and forget.

**A staffed agent roster.** 20 specialized agents with explicit model assignments — Opus for analysis, Sonnet for execution, Haiku for I/O. Reassign any agent's model with `devflow agents`, including GPT models through external model routing (`devflow proxy`).

**Up to 20 parallel Review agents.** Security, architecture, performance, complexity, consistency, regression, testing, and more. Each produces findings with severity, confidence scoring, and concrete fixes. Conditional Review agents activate when relevant (language focuses such as TypeScript for `.ts` files, database for schema changes, compliance when regulated surface detected in the diff). The gate level narrows these sets: the default `standard` level drops the TypeScript focus, and `lean` runs fewer focuses still. Every finding gets validated and resolved automatically.

**Memory that persists.** Session context survives restarts, `/clear`, and context compaction. Your agent picks up exactly where it left off.

**Decisions and pitfalls.** A background agent detects architectural decisions and known pitfalls from your session dialogs and writes them to `.devflow/curation/decisions.md` and `.devflow/curation/pitfalls.md` — informing every future review and implementation session without any manual bookkeeping.

**Feature knowledge bases.** Curated `KNOWLEDGE.md` files per feature area — patterns, conventions, and gotchas — git-tracked and shared with your team. Planning, implementation, and review workflows load them automatically and refresh them after changes.

**Always-on rules.** 13 ultra-condensed engineering principles (~10 lines each) load on every prompt — security, quality, and language-specific guidance (TypeScript, React, Go, Python, Java, Rust), plus a compliance rule when compliance is enabled. Rules install from your selected plugins only, so a Go project won't get React rules. Override any rule via `~/.devflow/rules/{name}.md` or `devflow rules shadow <name>`.

**Plain-English replies, opt-in.** Off by default. `devflow behavior --enable` (or `devflow init --behavior`) adds one rule that asks agents to write replies in ASD-STE100 Simplified Technical English: short sentences, one idea each, common words. `devflow behavior --disable` removes it, and `devflow behavior --status` shows where it stands.

**42 skills** (41 plugin-owned + 1 feature-owned compliance skill, installed on every machine). Skills install for the plugins you selected plus whatever those plugins declare they use, so the default plugin set installs 33 of the 41 and a Go project never gets the React skill. Most are grounded in expert material — backed by peer-reviewed papers, canonical books, and industry standards: security (OWASP, Shostack), architecture (Parnas, Evans, Fowler), performance (Brendan Gregg), testing (Beck, Meszaros), design (Wlaschin, Hickey), compliance (GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, SOX, NIST SSDF, OWASP ASVS), 200+ sources total.

**Skill shadowing.** Override any built-in skill with your own version. Drop a file into `~/.devflow/skills/{name}/` and the installer uses yours instead of the default — same activation, your rules. A shadow for a skill outside your plugin selection stays where it is: not installed, never deleted, and live again the moment you select that plugin.

**Compliance built in.** Six regulatory frameworks — GDPR, HIPAA, PCI DSS, SOC 2, ISO 27001, SOX. Every install carries the review skill with all six framework references; `devflow compliance --enable` adds an always-on rule for exactly the frameworks you select. A repository can declare its own frameworks in `.devflow/project.json` (`"compliance":["hipaa"]`), and the compliance review then runs there on any machine — with your machine's frameworks plus the repository's, loading only those references — without ever touching your rule. Compliance reviews activate automatically when a diff touches regulated surface. Enabling it on your machine also makes `required` the floor of your team's [evidence policy](#evidence-policy) on your machine: tracker-linked PRs, checked test plans, traced releases and a non-author approval before a PR reads merge-ready.

**Your issue tracker, not just GitHub.** Pick the tracker your team actually uses — GitHub, Jira, or Linear — at `devflow init`, with `devflow init --tracker <id>`, or later with `devflow tracker --set <id>`; that sets your machine's default. A repository can select its own in `.devflow/project.json`, and devflow follows it there automatically — one machine can work on a Jira repository 
````
