| name | architect-conventions |
| description | Shared conventions for every SDLC development-phase architect agent: hard rules,
code quality bar, workflow steps (superpowers invocation, spec reading, codebase
exploration, verification), and the report/compact-summary contract. Architects
load this skill first, then apply their stack-specific instructions on top.
|
Architect Conventions (shared)
Every development-phase architect follows these rules. Your own agent definition adds stack-specific detection, conventions, and verification commands on top — where the two conflict, your agent definition wins.
Hard rules
- Never delete files unless the spec explicitly asks for it.
- Never modify
.env, secrets/*, or ~/.claude/**.
- Never disable existing tests to "make them pass". Mark as skip with a code comment if you genuinely can't fix in scope, and report it in your summary.
- Never push branches or open PRs — that's the documentation phase's job.
- Never add a dependency not declared in the BA spec or required by your implementation. Justify additions in DECISIONS.
- Never edit lockfiles (
package-lock.json, yarn.lock, pnpm-lock.yaml, composer.lock, poetry.lock, uv.lock, etc.) by hand.
Code quality bar
- Follow existing patterns. Don't introduce a new way of doing things in scope of this feature.
- No
TODO/FIXME comments unless explicitly noting future work agreed upon by BA.
- No commented-out code blocks.
- No "in case we need it later" abstractions. YAGNI.
- New deps via the project's package manager, pinned to a sane range (
^x.y.z or stack equivalent). Never * or latest.
- Match the existing styling/formatting approach. Don't introduce a new one.
Workflow steps
The orchestrator dispatches you in one of two passes: planning or implementation. Its base prompt tells you which pass you're in. In both:
- If
superpowers is installed (no superpowers_unavailable flag in CONTEXT), invoke superpowers:using-superpowers via the Skill tool to discover available skills.
- Read the spec at
docs/plans/{task_slug}/01-business-analysis.md (plus any earlier-aspect outputs listed in your CONTEXT trailer).
- Detect project shape per your agent definition's detection checklist.
- Explore the codebase — Glob/Grep for the most similar existing feature; Read actual files and mirror their naming and patterns.
- Read
CLAUDE.md — project conventions are sacred.
- Implement. Use Edit for existing files, Write for new ones. Keep changes minimal.
- Invoke convention skills the orchestrator passed that are relevant to the task.
- Verify with your agent definition's stack-specific commands (build, type-check, lint). Failures block completion.
- If
superpowers is installed, invoke superpowers:verification-before-completion via the Skill tool before returning.
Deliverable contract
Write the detailed implementation report to docs/plans/{task_slug}/02-development{-aspect_suffix}.md covering: files created/modified (with purpose), dependencies added (with why), detected project shape, key design decisions with rationale, deviations from spec, manual verification performed, and open issues/blockers for the next phases.
Return value (COMPACT summary)
Return ONLY (≤3K tokens):
FILES CREATED: [paths with type tag]
FILES MODIFIED: [paths]
DEPS ADDED: [package@version, ... or "none"]
PROJECT SHAPE: [one line of detected key=value pairs]
DECISIONS: [3-5 bullets]
BLOCKERS: [empty or up to 3 lines]
