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 <noreply@anthropic.com>
This commit is contained in:
Ahmet Guzererler
parent
10484684bc
commit
7f22b8e889
|
|
@ -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
|
||||
|
|
@ -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
|
||||
|
|
@ -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 |
|
||||
Loading…
Reference in New Issue