From 7f22b8e889a2e0a7fa6c4b4a4e629be12aa3969f Mon Sep 17 00:00:00 2001 From: Ahmet Guzererler Date: Tue, 17 Mar 2026 20:26:15 +0100 Subject: [PATCH] feat: add architecture-coordinator skill for mandatory ADR reading protocol New Claude Code skill that enforces reading docs/agent/CURRENT_STATE.md, decisions/, and plans/ before any code changes. Includes conflict resolution protocol that stops work and quotes the violated ADR rule when user requests conflict with established architectural decisions. Files: - .claude/skills/architecture-coordinator/SKILL.md - .claude/skills/architecture-coordinator/references/adr-template.md - .claude/skills/architecture-coordinator/references/reading-checklist.md Co-Authored-By: Claude Sonnet 4.6 --- .../skills/architecture-coordinator/SKILL.md | 147 ++++++++++++++++++ .../references/adr-template.md | 92 +++++++++++ .../references/reading-checklist.md | 84 ++++++++++ 3 files changed, 323 insertions(+) create mode 100644 .claude/skills/architecture-coordinator/SKILL.md create mode 100644 .claude/skills/architecture-coordinator/references/adr-template.md create mode 100644 .claude/skills/architecture-coordinator/references/reading-checklist.md diff --git a/.claude/skills/architecture-coordinator/SKILL.md b/.claude/skills/architecture-coordinator/SKILL.md new file mode 100644 index 00000000..6c2b1374 --- /dev/null +++ b/.claude/skills/architecture-coordinator/SKILL.md @@ -0,0 +1,147 @@ +--- +name: Architecture-First Reading Protocol +description: > + This skill should be used at the start of every new technical task, new session, + or when switching to a different part of the codebase. It enforces mandatory reading + of architectural decisions, current project state, and active plans before any code + is written, modified, or proposed. Relevant when the user says "implement a feature", + "fix a bug", "refactor code", "add a new module", "modify configuration", "change architecture", + "start a task", "begin work on", "let's build", or "work on". This skill acts as a gatekeeper + ensuring all code changes respect established Architecture Decision Records (ADRs). +version: 0.1.0 +--- + +# Architecture-First Reading Protocol + +## Purpose + +Enforce a mandatory reading sequence before writing any code, modifying configurations, +or proposing solutions. All established architectural rules in `docs/agent/decisions/` +are treated as absolute laws. Violating an ADR without explicit user approval is forbidden. + +## Mandatory Reading Sequence + +Execute the following steps **in order** before producing any code or solution. + +### Step 1: Read Current State + +Read `docs/agent/CURRENT_STATE.md` to understand: + +- The active milestone and sprint focus +- Any blockers or constraints currently in effect +- Recent changes that affect the working context + +If the file does not exist, note this and proceed — but flag it to the user as a gap. + +### Step 2: Query Architectural Decisions + +List all files in `docs/agent/decisions/` and identify which ADRs are relevant to the +current task. If this directory does not exist, skip to Step 3. + +**Relevance matching rules:** + +- Match by filename keywords (e.g., task involves "auth" → read `0002-jwt-auth.md`) +- Match by YAML `tags` in ADR frontmatter if present +- When uncertain, read the ADR — false positives cost less than missed constraints + +**For each relevant ADR, extract and internalize:** + +- `Consequences & Constraints` section → treat as hard rules +- `Actionable Rules` section → treat as implementation requirements +- `Status` field → only `accepted` or `active` ADRs are binding + +See `references/adr-template.md` for the expected ADR structure. + +### Step 3: Check Active Plans + +List files in `docs/agent/plans/` and identify any plan related to the current task. +If this directory does not exist, skip to Step 4. + +- Read the active plan to determine which step is currently being executed +- Do not skip steps unless the user explicitly instructs it +- If no plan exists for the task, proceed but note the absence + +### Step 4: Acknowledge Reading + +Begin the first response to any technical task with a brief acknowledgment: + +``` +I have reviewed: +- `CURRENT_STATE.md`: [one-line summary] +- `decisions/XXXX-name.md`: [relevant constraint noted] +- `plans/active-plan.md`: [current step] + +Proceeding with [task description]... +``` + +If no docs exist yet, state: + +``` +No architecture docs found in docs/agent/. Proceeding without ADR constraints. +Consider scaffolding the agent memory structure if this project needs architectural governance. +``` + +## Conflict Resolution Protocol + +When a user request contradicts an ADR rule: + +1. **STOP** — do not write or propose conflicting code +2. **Quote** the specific rule from the decision file, including the file path +3. **Inform** the user of the conflict clearly: + +``` +⚠️ Conflict detected with `docs/agent/decisions/XXXX-name.md`: + +Rule: "[exact quoted rule]" + +Your request to [description] would violate this constraint. + +Options: + A) Modify the approach to comply with the ADR + B) Update the ADR to allow this exception (I can draft the amendment) + C) Proceed with an explicit architectural exception (will be logged) +``` + +4. **Wait** for the user's decision before proceeding + +## Directory Structure Expected + +``` +docs/agent/ +├── CURRENT_STATE.md # Active milestone, blockers, context +├── decisions/ # Architecture Decision Records +│ ├── 0001-example.md +│ ├── 0002-example.md +│ └── ... +├── plans/ # Active implementation plans +│ ├── active-plan.md +│ └── ... +└── logs/ # Session logs (optional) +``` + +## Graceful Degradation + +Handle missing documentation gracefully: + +| Condition | Action | +|---|---| +| `docs/agent/` missing entirely | Proceed without constraints; suggest scaffolding | +| `CURRENT_STATE.md` missing | Warn user, continue to decisions check | +| `decisions/` empty | Note absence, proceed without ADR constraints | +| `plans/` empty | Proceed without plan context | +| ADR has no `Status` field | Treat as `accepted` (binding) by default | + +## Integration with Existing Workflows + +This protocol runs **before** the existing TradingAgents flows: + +- Before the Agent Flow (analysts → debate → trader → risk) +- Before the Scanner Flow (scanners → deep dive → synthesis) +- Before any CLI changes, config modifications, or test additions + +## Additional Resources + +### Reference Files + +- **`references/adr-template.md`** — Standard ADR template for creating new decisions +- **`references/reading-checklist.md`** — Quick-reference checklist for the reading sequence diff --git a/.claude/skills/architecture-coordinator/references/adr-template.md b/.claude/skills/architecture-coordinator/references/adr-template.md new file mode 100644 index 00000000..7f317897 --- /dev/null +++ b/.claude/skills/architecture-coordinator/references/adr-template.md @@ -0,0 +1,92 @@ +# ADR Template + +Architecture Decision Records follow this structure. Use this template when creating +new decisions in `docs/agent/decisions/`. + +## Filename Convention + +``` +NNNN-short-descriptive-name.md +``` + +- `NNNN` — zero-padded sequential number (0001, 0002, ...) +- Use lowercase kebab-case for the name portion + +## Template + +```markdown +--- +title: "Short Decision Title" +status: proposed | accepted | deprecated | superseded +date: YYYY-MM-DD +tags: [relevant, keywords, for, matching] +superseded_by: NNNN-new-decision.md # only if status is superseded +--- + +# NNNN — Short Decision Title + +## Context + +Describe the problem, forces at play, and why a decision is needed. +Include relevant technical constraints, business requirements, and +any alternatives considered. + +## Decision + +State the decision clearly and concisely. Use active voice. + +Example: "Use JWT tokens for API authentication with RS256 signing." + +## Consequences & Constraints + +List the binding rules that follow from this decision. These are +treated as **absolute laws** by the Architecture-First Reading Protocol. + +- **MUST**: [mandatory requirement] +- **MUST NOT**: [explicit prohibition] +- **SHOULD**: [strong recommendation] + +Example: +- MUST use RS256 algorithm for all JWT signing +- MUST NOT store tokens in localStorage +- SHOULD rotate signing keys every 90 days + +## Actionable Rules + +Concrete implementation requirements derived from the decision: + +1. [Specific code/config requirement] +2. [Specific code/config requirement] +3. [Specific code/config requirement] + +## Alternatives Considered + +| Alternative | Reason Rejected | +|---|---| +| Option A | [why not chosen] | +| Option B | [why not chosen] | + +## References + +- [Link or file reference] +- [Related ADR: NNNN-related.md] +``` + +## Status Lifecycle + +``` +proposed → accepted → [deprecated | superseded] +``` + +- **proposed** — Under discussion, not yet binding +- **accepted** — Active and binding; all code must comply +- **deprecated** — No longer relevant; may be ignored +- **superseded** — Replaced by another ADR (link via `superseded_by`) + +## Best Practices + +- Keep decisions focused — one decision per file +- Write constraints as testable statements where possible +- Tag decisions with module/domain keywords for easy matching +- Reference related decisions to build a decision graph +- Date all decisions for historical context diff --git a/.claude/skills/architecture-coordinator/references/reading-checklist.md b/.claude/skills/architecture-coordinator/references/reading-checklist.md new file mode 100644 index 00000000..dc6af768 --- /dev/null +++ b/.claude/skills/architecture-coordinator/references/reading-checklist.md @@ -0,0 +1,84 @@ +# Architecture Reading Checklist + +Quick-reference checklist for the mandatory reading sequence. +Execute before every technical task. + +## Pre-Flight Checklist + +``` +[ ] 1. Read docs/agent/CURRENT_STATE.md + → Note active milestone + → Note blockers + → Note recent context changes + +[ ] 2. List docs/agent/decisions/*.md + → Identify ADRs relevant to current task + → For each relevant ADR: + [ ] Read Consequences & Constraints + [ ] Read Actionable Rules + [ ] Verify status is accepted/active + [ ] Note any hard prohibitions (MUST NOT) + +[ ] 3. List docs/agent/plans/*.md + → Find active plan for current task + → Identify current step in plan + → Do not skip steps without user approval + +[ ] 4. Acknowledge in response + → List reviewed files + → Summarize relevant constraints + → State intended approach +``` + +## Quick Relevance Matching + +To find relevant ADRs efficiently: + +1. **Extract keywords** from the task description +2. **Match against filenames** in `docs/agent/decisions/` +3. **Check YAML tags** in ADR frontmatter +4. **When in doubt, read it** — a false positive is cheaper than a missed constraint + +### Common Keyword → ADR Mapping Examples + +| Task Keywords | Likely ADR Topics | +|---|---| +| auth, login, token, session | Authentication, authorization | +| database, schema, migration | Data layer, ORM, storage | +| API, endpoint, route | API design, versioning | +| deploy, CI/CD, pipeline | Infrastructure, deployment | +| LLM, model, provider | LLM configuration, vendor routing | +| agent, graph, workflow | Agent architecture, LangGraph | +| config, env, settings | Configuration management | +| test, coverage, fixture | Testing strategy | + +## Conflict Response Template + +When a conflict is detected, use this template: + +``` +⚠️ Conflict detected with `docs/agent/decisions/XXXX-name.md`: + +Rule: "[exact quoted rule from Consequences & Constraints or Actionable Rules]" + +Your request to [brief description of the conflicting action] would violate this constraint. + +Options: + A) Modify the approach to comply with the ADR + B) Update the ADR to allow this exception (I can draft the amendment) + C) Proceed with an explicit architectural exception (will be logged) + +Which option do you prefer? +``` + +## Graceful Degradation Quick Reference + +| Missing Resource | Action | +|---|---| +| Entire `docs/agent/` | Proceed; suggest scaffolding the directory structure | +| `CURRENT_STATE.md` only | Warn, continue to decisions | +| `decisions/` empty | Note absence, proceed freely | +| `plans/` empty | Proceed without plan context | +| ADR missing `Status` | Default to `accepted` (binding) | +| ADR status `proposed` | Informational only, not binding | +| ADR status `deprecated` | Ignore, not binding |