Defame1297
74f5e1840d
13 manual scenarios run across instructions and governance layers (two rounds for failures). Fixed four rules that lost to RLHF defaults: - Exploratory question format: tightened with boundary framing; added @import CONTEXT.md to repo CLAUDE.md and a standing rule to check docs/adr/ and ROADMAP resolved entries before answering design questions (3-round iteration to resolve) - File-edit intent: added counter-example to stop clarification-seeking - Push confirmation: reframed as "do not call the tool" not "ask first" - Secrets rule: extended to cover credential reproduction in response text and usage examples, with explicit placeholder requirement Scenario 4 (push confirmation) inconclusive — no remote configured. Governance scenario 3 (HITL on real infra) untestable — Nginx not installed. Both share the same root cause: agent delegates to permission system. Also corrects stale skill list in docs/spec/overview.md (12 actual deployed skills vs 16 names previously listed). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
56 lines
3.3 KiB
Markdown
56 lines
3.3 KiB
Markdown
> [!WARNING]
|
|
> **This is the repo meta-config.** It tells Claude how to work *inside this repository itself* — structure, conventions, how to add skills/workflows/providers.
|
|
>
|
|
> It is NOT the global config deployed to `~/.claude/`. That file lives at `providers/claude-code/CLAUDE.md`. Do not conflate the two.
|
|
|
|
# Working in this repo
|
|
|
|
This repo is the global AI development configuration repository — the authoritative source for agent definitions, skills, workflows, and prompts across all projects.
|
|
|
|
## Structure
|
|
|
|
- `core/` — provider-agnostic source of truth (plain language, no tool-specific references)
|
|
- `.agents/skills/` — canonical skills location (Agent Skills standard); deployed to `~/.agents/skills/` via `install.sh`
|
|
- `providers/claude-code/` — Claude Code adapter (deployed to `~/.claude/` via `install.sh`)
|
|
- `docs/` — project documentation, PRDs, and issues
|
|
- `scripts/` — install.sh (sync.sh and init-project.sh come in Chunk 6)
|
|
- `tests/` — test scripts
|
|
|
|
## Key documents
|
|
|
|
@CONTEXT.md
|
|
|
|
Read these on demand:
|
|
|
|
- `docs/VISION.md` — purpose, goals, and long-term Management Application vision
|
|
- `docs/spec/overview.md` — current deployed state; what works today
|
|
- `docs/spec/architecture.md` — current directory structure, install pipeline, provider model
|
|
- `docs/ROADMAP.md` — chunk status table and open questions; read this to orient on where work stands
|
|
- `docs/adr/` — architectural decisions; read before answering design questions or proposing structural changes
|
|
- `docs/ai-constitution.md` — full governance evidence base; read when a governance decision needs justification
|
|
- `docs/HUMANS.md` — human practitioner checklist; applies when working with AI tools in this repo
|
|
- **Governance workstream** — `core/instructions/governance.md` (agent rules), loaded via `@import` in `providers/claude-code/CLAUDE.md`; `docs/research/governance_principles/CONTROLS.md` (Phase 2 enforcement spec, Chunk 6)
|
|
|
|
## Key rules
|
|
|
|
- `core/` content must use plain imperative language — no tool names, provider APIs, or format assumptions
|
|
- Never edit files deployed by `sync.sh` directly in a project; put customizations in override files
|
|
- `providers/claude-code/CLAUDE.md` is the deployed global config — edit it there, not here
|
|
- Governance constraints from `core/instructions/governance.md` apply when building content in this repo — hard prohibitions on secrets and data, HITL requirements before irreversible actions, sycophancy resistance, and deterministic execution preference are always in effect
|
|
|
|
## Chunk development workflow
|
|
|
|
Each chunk follows this sequence:
|
|
1. `/grill-with-docs` — grill vision/context before writing anything
|
|
2. `/to-prd` — write the PRD from the grilling output
|
|
3. `/to-issues` — break PRD into issues (`docs/issues/` until Gitea is set up)
|
|
4. `/tdd` — implement each issue using TDD
|
|
5. `/improve-codebase-architecture` — architecture review after implementation
|
|
6. Start a new session before the next chunk
|
|
|
|
Don't skip `/tdd` — it's the easy one to forget.
|
|
|
|
## Working context
|
|
|
|
This repo is built by a junior developer as a homelab tool intended to scale to professional environments. Challenge ideas and reference industry standards rather than validate assumptions. Explain the why behind decisions — assume the user is learning, not just executing. Flag significant actions before taking them.
|