Skip to content

Conversation

@sgbett
Copy link
Contributor

@sgbett sgbett commented Jan 25, 2026

Summary

  • Fixes the copy command in setup-architect to reference the correct nested path

Problem

The framework files are in the .architecture subfolder of the cloned repo, not at the repo root. The copy command was copying repo documentation (README.md, USAGE*.md, tools/, mcp/, etc.) instead of just the framework template files.

Fix

Changed line 57 in .claude/skills/setup-architect/references/installation-procedures.md:

- cp -r .architecture/.architecture/* .architecture/
+ cp -r .architecture/.architecture/.architecture/* .architecture/

Test plan

  • Verified fix installs only framework files (members.yml, principles.md, config.yml, templates/, etc.)
  • Confirmed repo documentation files are no longer copied to user projects

Fixes #4

🤖 Generated with Claude Code

The framework files are in the .architecture subfolder of the cloned
repo, not at the repo root. The copy command was copying repo
documentation (README.md, USAGE*.md, tools/, etc.) instead of just
the framework template files.

Changed:
  cp -r .architecture/.architecture/* .architecture/
To:
  cp -r .architecture/.architecture/.architecture/* .architecture/

Fixes #4

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@codenamev codenamev merged commit 203694b into codenamev:main Jan 25, 2026
10 checks passed
@codenamev
Copy link
Owner

Thank you for your contribution!

@sgbett
Copy link
Contributor Author

sgbett commented Feb 10, 2026

This PR correctly fixed the copy path in installation-procedures.md. However, experience since merging has shown that the fix doesn't reliably solve the problem — the LLM still improvises the command rather than following the documented procedure exactly. The installation has failed in multiple subsequent sessions.

The underlying issue is that installation-procedures.md is a reference document that the LLM interprets, not executes. Fixing the text makes it accurate, but accuracy doesn't guarantee the LLM will follow it. See #8 for the proper solution: a shell script that handles all deterministic file operations, removing the LLM from the execution path entirely.

🤖 Generated with Claude Code

sgbett added a commit to bettison-org/ai-software-architect that referenced this pull request Feb 12, 2026
* feat: add install-framework.sh for deterministic installation

Shell script handling all file operations for the setup-architect
skill: prerequisites check, framework file copy (using the exact
PR codenamev#5 path), clone removal, directory creation, config initialisation,
doc cleanup, and safe .git removal with all 5 safeguards.

Structured status tokens on stdout, errors on stderr, and specific
exit codes for each failure mode. This replaces LLM-interpreted
bash commands that caused repeated installation failures.

First implementation of ADR-009 (script-based deterministic operations).
Trigger condition met: bash command construction caused bugs (codenamev#4/codenamev#5).

Refs codenamev#8

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add next-adr-number.sh for deterministic ADR prefix generation

Shell script that reads numbering config from .architecture/config.yml
and returns the correct ADR prefix. Supports sequential (zero-padded)
and date-based (strftime format) numbering.

Config options:
  numbering_format: sequential | date-based
  sequential_format: "000"   (zero-padding width, default: 3 digits)
  date_format: "%Y%m%d"      (strftime format, default: YYYYMMDD)

Includes collision detection: exits non-zero if an ADR with the same
prefix and topic already exists, alerting the user to a likely duplicate.

Supersedes PR codenamev#7 which documented date-based numbering as LLM-interpreted
instructions — this makes the config deterministic.

Refs codenamev#8

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat: add sequential_format and date_format ADR config options

Expand ADR numbering configuration with explicit format strings:
- sequential_format: zero-padding pattern ("000" = 3 digits)
- date_format: strftime format string ("%Y%m%d" = YYYYMMDD)

Both are commented out with sensible defaults, making them
self-documenting. Backward compatible with existing
numbering_format: sequential | date-based.

Refs codenamev#8

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: restructure setup-architect to use install script

Collapse 9-step workflow to 7 steps by replacing the three
deterministic steps (prerequisites, install, cleanup) with a single
invocation of install-framework.sh.

Project analysis now runs first (before installation) so the LLM
knows the tech stack before customisation begins.

All file operations are now handled by the script — the skill
only handles interpretive work (project analysis, team customisation,
principles, initial analysis, reporting).

Refs codenamev#8

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: replace inline bash with script interface docs

Remove ~250 lines of bash code blocks from installation-procedures.md
that are now handled by install-framework.sh. Replace with script
interface documentation (arguments, exit codes, status tokens),
troubleshooting, and recovery procedures.

The reference file's role changes from "instructions for the LLM to
interpret" to "documentation for when things go wrong."

Refs codenamev#8

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: use American English spelling in upstream project files

British spellings (customise, analyse, initialise, prioritise) were
incorrectly introduced from personal CLAUDE.md preferences. This is an
upstream project that uses American English throughout.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* refactor: replace inline ADR numbering with next-adr-number.sh

The create-adr skill now invokes the deterministic numbering script
instead of constructing bash commands inline. This ensures config
options (numbering_format, sequential_format, date_format) are always
respected, and adds collision detection for duplicate ADR topics.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* docs: add script-based deterministic operations pattern

Documents the pattern for extracting deterministic operations into shell
scripts, first implementation of ADR-009. Includes when-to-script
criteria, interface conventions, script location conventions, and the
background that triggered implementation. Also updates create-adr
permission scope in the permissions table.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* test: add CI tests for install-framework.sh and next-adr-number.sh

Tests the actual scripts deterministically rather than simulating what
the LLM might do. Covers:

install-framework.sh:
- Success path (copy, cleanup, verify)
- Missing clone (exit 1)
- Relative path rejection (exit 1)

next-adr-number.sh:
- Sequential default (001, 002, 003)
- Sequential custom padding (0001)
- Date-based default (%Y%m%d)
- Date-based custom format (%Y-%m-%d)
- Collision detection (exit 2)
- Missing config falls back to defaults

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
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.

Bug: setup-architect copies repo root files instead of framework files

2 participants