architect-conventions
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 re
SKILL.mdplugins/sdlc/skills/architect-conventions/SKILL.md
GitHubArchitect 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/FIXMEcomments 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.zor stack equivalent). Never*orlatest. - 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
superpowersis installed (nosuperpowers_unavailableflag in CONTEXT), invokesuperpowers:using-superpowersvia 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 — start from the
project_shape:block in your CONTEXT trailer (package manager, runner prefix, test / lint / typecheck / format commands, test framework, CI, monorepo), computed once per session byscripts/detect-stack.sh. Run your agent definition's detection checklist only for keys that arenullthere — re-deriving a known answer is paid in tokens on every pass. - 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, compile, import smoke test). Failures block completion. Formatters and the batched typecheck/lint are hook-driven — the stack plugin's PostToolUse hook formats every file you write and its SubagentStop hook runs the typecheck or linter once after you return, relaying failures to the orchestrator as a retry hint — so do not run those yourself.
- If
superpowersis installed, invokesuperpowers:verification-before-completionvia 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]