AI_template/DOCS.md

Project Documentation Index: Starter Template

Technical index for developers and AI agents. Use this as the entry point to all docs/ files.

---

Documentation Languages

• Technical docs: English (docs/ and subfolders).
• Repository summary: README.md (English). New documents should be added in English unless noted.

---

Documentation Structure (root: docs/)

1) General Project Docs

• docs/archetypes.md — product archetypes and optional modules; pick what applies.
• docs/project-overview.md — goals, target users, chosen archetype, key flows (pick relevant), non-functional requirements.
• docs/phases-plan.md — Phase 0–4 plan with tasks across product, frontend, backend, infra, data/LLM.
• docs/content-structure.md — high-level UI/content structure and page sections (archetype‑specific examples).
• docs/dev-setup.md — local/CI setup once code exists.

1c) Architecture Decision Records (/docs/adr)

• docs/adr/README.md — how ADRs work.
• docs/adr/0000-template.md — ADR template.

1b) LLM / AI System (/docs/llm)

• docs/llm/prompting.md — prompt structure, versioning, output schemas.
• docs/llm/evals.md — evaluation strategy, datasets, regression gates.
• docs/llm/safety.md — privacy, injection defenses, reasoning_trace policy.
• docs/llm/caching-costs.md — caching layers, budgets, monitoring.
• docs/llm/rag-embeddings.md — RAG/embeddings design and evaluation.

2) Frontend (/docs/frontend)

• docs/frontend/overview.md — frontend scope and key user journeys (depends on archetype/modules).
• docs/frontend/architecture.md — canonical, locked frontend decisions (after Phase 1).
• docs/frontend/FRONTEND_ARCHITECTURE_PLAN.md — working architecture notes; archive/delete after Phase 1.
• docs/frontend/ui-ux-guidelines.md — UX/UI guidance for data review and approval flows.
• docs/frontend/seo-performance.md — performance and SEO recommendations.

3) Backend (/docs/backend)

• docs/backend/overview.md — backend scope (integrations, AI capability, optional pipelines/approvals/billing).
• docs/backend/architecture.md — canonical, locked backend decisions (after Phase 1).
• docs/backend/api-design.md — API resources and conventions (entities, rules, approvals, reports, billing, events).
• docs/backend/security.md — authN/Z, secret handling, webhook verification, audit/event logging.
• docs/backend/payment-flow.md — payment integration (provider-agnostic template; single source of truth for payment flows and webhooks).

4) CI/CD & Deployment

• docs/ci-cd.md — Woodpecker CI + Gitea setup, pipeline flow, deploy script, sudoers config, troubleshooting.

5) Examples (/docs/examples)

• docs/examples/RECOMMENDATIONS-example.md — filled-in example of RECOMMENDATIONS.md for a compliance classifier (Archetype C).

---

Root-Level Files

• README.md — project overview and quick start.
• RULES.md — core repository rules for AI agents.
• RECOMMENDATIONS.md — project-specific decisions and overrides (template).
• CONTRIBUTING.md — commit conventions, PR rules, how to add docs/agents/ADRs.
• SECURITY.md — vulnerability disclosure policy.
• RESEARCH-SDD-TOOLS.md — SDD tools research (Spec Kit, AI Factory).
• LICENSE — MIT license.
• package.json — project metadata and Node.js engine requirement.
• .env.example — environment variables template.
• .editorconfig — editor formatting standards (indentation, line endings).
• .woodpecker.yml — Woodpecker CI pipeline config (local backend).
• scripts/setup-project.sh — Automated VPS setup for new projects (user, dir, deploy, sudoers, systemd, nginx).
• scripts/deploy.sh — VPS deploy script template (rsync + npm ci + systemctl).
• scripts/ci-lint-fix.sh — ESLint auto-fix with commit-back for CI.

Agent Profiles (/agents)

• agents/README.md — agent index, selection guide, model/tools reference, and shared context7 guidelines.
• agents/planner.md — implementation planner (opus) — task breakdown, risk assessment, phased plans.
• agents/frontend-architect.md — frontend specialist (opus) — React, Next.js, accessibility, performance.
• agents/backend-architect.md — backend specialist (opus) — system design, databases, APIs.
• agents/security-auditor.md — security review (opus) — OWASP, auth, vulnerability assessment.
• agents/code-reviewer.md — code quality and PR review (sonnet).
• agents/test-engineer.md — testing specialist (sonnet) — strategy, automation, CI/CD.
• agents/prompt-engineer.md — LLM prompt design and optimization (sonnet).
• agents/documentation-expert.md — technical writing, user/admin guides, docs maintenance (sonnet).
• agents/build-error-resolver.md — build/type/lint error fixer (sonnet) — minimal-diff fixes.
• agents/loop-operator.md — autonomous loop monitor (sonnet) — stall detection, escalation.

Claude Code Skills (/.claude/skills)

• .claude/skills/update-status/ — sync project status across docs after milestone.
• .claude/skills/phase-transition/ — full phase transition with verification.
• .claude/skills/init-project/ — interactive project initialization wizard.
• .claude/skills/component/ — scaffold accessible React component (frontend-architect).
• .claude/skills/a11y-audit/ — WCAG 2.2 AA accessibility audit (frontend-architect).
• .claude/skills/api-endpoint/ — scaffold REST API endpoint (backend-architect).
• .claude/skills/db-schema/ — design database schema with migration (backend-architect).
• .claude/skills/security-audit/ — OWASP security audit of git diff (security-auditor).
• .claude/skills/threat-model/ — threat modeling with risk tiers (security-auditor).
• .claude/skills/write-tests/ — write tests with Vitest + Testing Library (test-engineer).
• .claude/skills/test-plan/ — test strategy and coverage plan (test-engineer).
• .claude/skills/review/ — code review of current git diff (code-reviewer).
• .claude/skills/review-pr/ — Gitea PR review by number (code-reviewer).
• .claude/skills/improve-prompt/ — diagnose and improve LLM prompt (prompt-engineer).
• .claude/skills/create-skill/ — create or improve a Claude Code skill (meta-skill).
• .claude/skills/search-first/ — research existing solutions before building custom code.
• .claude/skills/verification-loop/ — full quality gate pipeline (Build→TypeCheck→Lint→Test→Security→Diff).
• .claude/skills/strategic-compact/ — when and how to run /compact effectively.
• .claude/skills/autonomous-loops/ — patterns for autonomous agent workflows (6 levels).
• .claude/skills/continuous-learning/ — extract session learnings into instincts and memory.

Claude Code Hooks (/.claude/hooks)

Profile System

Hooks use a profile system (minimal|standard|strict) controlled by CLAUDE_HOOK_PROFILE env var (default: standard). Individual hooks can be disabled via CLAUDE_DISABLED_HOOKS env var (comma-separated filenames).

• .claude/hooks/run-with-profile.sh — profile gate wrapper for hooks.

Safety Hooks (always active)

• .claude/hooks/protect-files.sh — blocks edits to .env, lock files, .git/, keys.
• .claude/hooks/bash-firewall.sh — blocks destructive commands (rm -rf /, git reset --hard, etc.).
• .claude/hooks/audit-log.sh — logs all Bash commands with timestamp to audit.log.
• .claude/hooks/commit-docs-reminder.sh — reminds to check status-update-checklist.md before git commit.

Quality Hooks (standard+ profile)

• .claude/hooks/config-protection.sh — blocks modifications to linter/formatter config files.
• .claude/hooks/suggest-compact.sh — suggests /compact every ~50 tool calls.
• .claude/hooks/auto-tmux-dev.sh — suggests tmux for long-running dev server commands.

Strict-Only Hooks

• .claude/hooks/post-edit-format.sh — auto-formats files with Prettier after edits.

Session Persistence

• .claude/hooks/session-load.sh — restores previous session context on SessionStart.
• .claude/hooks/session-save.sh — saves session context (branch, files, commits) on Stop.
• .claude/sessions/ — session state storage directory.

Configuration

• .claude/settings.json — hooks configuration (PreToolUse, PostToolUse, SessionStart, Stop, Notification).

---

How to Use This Index

• New to the project: read project-overview.md and phases-plan.md first.
• Designing features: use frontend/backend architecture docs plus API/security/payment flow specs.
• Expanding docs: add new English *.md files under docs/ and update this index with links.
• Contributing: read CONTRIBUTING.md for commit conventions and PR rules.

Last Updated: Phase 0 (Planning)