olek/AI_template
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
AI_template/DOCS.md
olekhondera db5ba04fb9 feat: expand agents (10), skills (20), and hooks (11) with profile system 
Agents:
- Add YAML frontmatter (model, tools) to all 7 existing agents
- New agents: planner (opus), build-error-resolver (sonnet), loop-operator (sonnet)

Skills:
- search-first: research before building (Adopt/Extend/Compose/Build)
- verification-loop: full quality gate pipeline (Build→TypeCheck→Lint→Test→Security→Diff)
- strategic-compact: when and how to run /compact effectively
- autonomous-loops: 6 patterns for autonomous agent workflows
- continuous-learning: extract session learnings into instincts

Hooks:
- Profile system (minimal/standard/strict) via run-with-profile.sh
- config-protection: block linter/formatter config edits (standard)
- suggest-compact: remind about /compact every ~50 tool calls (standard)
- auto-tmux-dev: suggest tmux for dev servers (standard)
- session-save/session-load: persist and restore session context (Stop/SessionStart)

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-24 20:16:20 +02:00

164 lines
8.7 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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)
Reference in New Issue View Git Blame Copy Permalink