Skip to content

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

Closed
alfasin wants to merge 3 commits into
tikalk:mainfrom
alfasin:improve/architect-init-output-quality
Closed

alfasin wants to merge 3 commits into
tikalk:mainfrom
alfasin:improve/architect-init-output-quality

Conversation

@alfasin

@alfasin alfasin commented Feb 10, 2026 •

Copy link
Copy Markdown

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
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>
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

kanfil commented Feb 10, 2026

Copy link
Copy Markdown
Member

@alfasin fixed using another methods, upload latest version

@alfasin

alfasin commented Feb 11, 2026

Copy link
Copy Markdown
Author

Done

@kanfil

kanfil commented Feb 11, 2026

Copy link
Copy Markdown
Member

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

@alfasin

alfasin commented Feb 11, 2026

Copy link
Copy Markdown
Author

closing because the product that was generated was not as good.
we'll need to revise and compare to other outputs

@alfasin alfasin closed this Feb 11, 2026
kanfil added a commit that referenced this pull request Jul 27, 2026
Address Copilot review findings that left generated event hooks inert or
schema-invalid after the rework:

- #2: the resolved events map now carries an ordered list of handlers per
  event (dict[str, list[dict]]) so two extensions declaring the same event
  both run instead of the last one silently winning. collect_extension_events
  accumulates; every adapter emits one native entry per handler.
- #6: Claude/Gemini/Qwen/Devin/Tabnine native schema accepts a single
  'command' string, not command+args. Each adapter now renders one complete
  shell invocation of the dispatcher via _dispatcher_command().
- #7: Gemini measures hook timeouts in milliseconds; add events_timeout_unit
  attr and _native_timeout() so the 60s default becomes 60000ms instead of
  terminating the dispatcher after 60ms.
- #4: _resolve_event_command_argv() replaces _extract_script_path() —
  scripts: values are command strings (e.g. 'scripts/bash/setup-plan.sh --json'),
  not bare paths. Resolves the project's sh/ps/py variant, splits safely into
  argv, and prepends the interpreter for .py.
- #5: bundled-template fallback now uses _locate_core_pack()/_repo_root()
  (core_pack/commands, not the non-existent core_pack/templates/commands).
- #16: all formatters use IntegrationBase.resolve_python_interpreter() so
  generated commands honor the project venv and never hard-code python3
  (absent on Windows). The opencode TS plugin bakes in the same resolved
  interpreter.
- #13: opencode TS plugin runEvent() now throws on failure instead of
  process.exit(2), which killed the OpenCode host process; only the failing
  hook is rejected.
- #21: user YAML override is validated (event names, non-empty command
  strings) before returning; a malformed override is warned about and
  ignored rather than crashing installation on cfg.get().

Bump dev version 0.14.2.dev1 -> 0.14.2.dev2 (gemini/__init__.py change) and
add a CHANGELOG entry.

Refs: PR github#3704 Copilot inline review (findings #2, #4, #5, #6, #7, #13, #16, #21)

Assisted-by: opencode (model: glm-5.2, autonomous)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants