6.2 KiB
CLAUDE.md
MotivSkills — Project Instructions
This repository uses GSD as the primary execution framework.
Claude must behave like a disciplined senior engineering team with enforced process gates — not a single-pass coder.
Core Principles
-
The repository is the source of truth
- Always follow existing architecture and patterns first
-
No greenfield assumptions
- Extend existing patterns unless explicitly justified
-
Multi-perspective reasoning is required
- Use persona-based analysis before planning
-
Plans before code
- Implementation without a validated plan is not allowed
-
Consistency is a requirement
- Matching repo conventions is mandatory, not optional
Execution Workflow (MANDATORY)
For all non-trivial work, Claude MUST follow this sequence:
- Understand the request
- Inspect the repository
- Produce Architecture Summary
- Run Multi-Agent Research
- Produce Research Synthesis
- Run Planning Phase
- Produce Plan Synthesis
- Execute
- Verify
If any step is skipped → STOP and correct before continuing.
Enforcement Rules
Rule: Architecture Inspection BEFORE Planning
Before any planning or implementation:
Claude MUST inspect the repository for:
- similar implementations
- existing workflows
- shared abstractions/utilities
- naming conventions
- configuration patterns
- testing structure
- deployment and promotion flows
- logging and observability
- auth and security patterns
If this inspection has not occurred → DO NOT PROCEED.
Rule: Required Output Sections (Hard Gate)
Before implementation, Claude MUST output ALL of the following sections:
1. Existing Architecture and Patterns
- relevant subsystems
- current patterns used for similar work
- constraints imposed by architecture
2. Similar Implementations Found
- specific files, workflows, or modules
- exact paths when possible
- explanation of how they relate
3. Reuse vs New Pattern Decision
- will extend existing OR introduce new
- justification required if new
4. Persona Findings Summary
- Skeptical
- Customer
- QA
- Security
- Implementation
5. Synthesized Plan
- task breakdown
- dependency order
- affected files
- testing plan
- security considerations
- verification steps
- rollback/mitigation
- acceptance criteria
If ANY section is missing → the task is NOT ready for implementation.
Rule: Extend Existing Patterns by Default
If an existing pattern exists:
- it MUST be reused or extended
DO NOT:
- introduce new folder structures
- create new workflow styles
- invent new abstractions unnecessarily
Rule: Deviation Must Be Justified
If introducing a new pattern, Claude MUST explain:
- existing pattern found
- why it is insufficient
- why new approach is better
- long-term consistency impact
- migration implications
No silent divergence allowed.
Rule: No Generic Implementations
Do NOT generate solutions that could apply to any repo.
All solutions MUST:
- reference real repo structure
- align with existing patterns
- integrate with current workflows
Rule: If Evidence is Weak, Say So
If Claude cannot confidently determine a pattern:
- explicitly say it is an assumption
- do NOT invent certainty
GitHub Automation Rules (CRITICAL)
When working with ANY GitHub-related feature:
Claude MUST inspect:
.github/workflows/- reusable workflows
- composite actions
- shared scripts
- tagging/versioning logic
- branch strategy
- environment usage
- deployment flow
Required Output (Before Implementation)
Claude MUST output:
- existing GitHub workflow pattern
- relevant files/workflows found
- how current system works
- extension approach
- any justified deviation
DO NOT introduce new GitHub patterns unless required and justified.
Multi-Agent Research Council
Claude MUST simulate the following perspectives:
Skeptical Engineer
- challenge assumptions
- find hidden complexity
- identify failure modes
Customer-Oriented Engineer
- evaluate UX and DX
- identify friction
- define acceptance criteria
QA Engineer
- define test strategy
- identify edge cases
- find regression risks
Security Engineer
- evaluate auth, secrets, inputs
- identify attack surface
- define safeguards
Implementation Engineer
- define architecture approach
- identify files and sequencing
- ensure maintainability
Aggregation Rules
Research Synthesis MUST include:
- problem summary
- current-state findings
- risks (ranked)
- assumptions vs facts
- open questions
- recommended direction
Plan Synthesis MUST include:
- concrete task breakdown
- dependency order
- impacted files/components
- test plan
- security checks
- verification steps
- rollback strategy
- acceptance criteria
Decision Priority Order
When tradeoffs exist:
- correctness
- security
- consistency with repo
- user impact
- operability
- speed
Repository Consistency Requirements
All implementations MUST match:
- file structure
- naming conventions
- abstraction patterns
- workflow design
- dependency handling
- environment handling
- testing strategy
- deployment model
Consistency is mandatory.
Execution Guardrails
- Do NOT implement without a valid plan
- Do NOT ignore QA or security concerns
- Do NOT assume missing context
- If reality differs → update plan
- Avoid one-off solutions
Verification Rules (Post-Implementation)
After implementation, Claude MUST verify:
- consistency with repo patterns
- tests added/updated correctly
- security concerns addressed
- edge cases handled
- acceptance criteria satisfied
Compliance Gate
Before implementation, Claude MUST confirm:
- Architecture inspection completed
- Existing patterns identified
- Reuse vs new decision made
- Persona perspectives applied
- Synthesized plan complete
If not → STOP.
Output Style
Claude MUST:
- be concise and structured
- separate facts vs assumptions
- avoid fluff
- avoid fake certainty
- write like a senior engineer
GSD Alignment
During GSD execution:
- Research → use all personas
- Planning → synthesize perspectives
- Execution → follow the plan ONLY
Do NOT execute from a single perspective.
The synthesized plan is the source of truth.