Skip to content

feat: improve architect.init output quality with team-size calibration #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
alfasin wants to merge 3 commits into
base: main
Choose a base branch
from
Open

feat: improve architect.init output quality with team-size calibration #5

alfasin wants to merge 3 commits into from
+675 −22

Conversation

@alfasin
Copy link

@alfasin alfasin commented Feb 10, 2026 •
edited
Loading

Summary

  • Team-size calibration: Auto-detects team size from git history (or --team-size override) to scale output depth — small teams get lean templates and fewer ADRs, large teams get full Rozanski & Woods
  • Surprise-value heuristic: Only generates ADRs for non-obvious, surprising, or risky decisions — skips documenting ecosystem defaults like "PostgreSQL for relational data"
  • Risks & Gaps phase: Adds a new analysis phase identifying operational gaps, technical debt, single points of failure, and security concerns — the most valuable output, especially for small teams
  • Existing docs deduplication: Scans CLAUDE.md, README, CONTRIBUTING etc. before generating to avoid repeating what's already documented
  • ADR template improvements: Renames "Alternatives Considered" to "Common Alternatives" with neutral "Trade-offs" framing; adds "Discovered" status; removes fabricated rejection rationale for reverse-engineered ADRs
  • Lean architecture template: New AD-template-lean.md for small/medium teams

Test plan

  • Run setup-architecture.sh init on a solo-dev repo — should auto-detect "small" tier and use lean template
  • Run setup-architecture.sh init --team-size large — should use full template
  • Run /architect.init on a brownfield codebase — verify ADRs only cover surprising decisions
  • Verify --team-size flag parsing works with both --team-size=small and --team-size small forms
  • Check that existing docs (CLAUDE.md, README) are referenced and not duplicated

🤖 Generated with Claude Code

alfasin and others added 2 commits February 10, 2026 18:45
@alfasin @claude
feat: improve architect.init output quality with team-size calibration
cb67055 
Architect.init generated too much boilerplate for small teams and documented
obvious decisions. This adds team-size awareness (auto-detected from git history)
to calibrate output depth, a surprise-value heuristic to skip trivial ADRs,
and a risks/gaps analysis phase as the primary valuable output.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@alfasin @claude
fix: resolve template paths to use SPECKIT_TEMPLATES_DIR
b7063cb 
Template references were hardcoded to .specify/templates/ which doesn't
exist in release packages. Use a relative path from the script directory
instead.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
@kanfil
Copy link
Member

kanfil commented Feb 10, 2026

@alfasin fixed using another methods, upload latest version

@alfasin
Copy link
Author

alfasin commented Feb 11, 2026

Done

@kanfil
Copy link
Member

kanfil commented Feb 11, 2026

Sorry, I mean I already took your concepts into the main branch in a differ way, try to use the latest version to see the changes

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@alfasin @kanfil