Skip to content

[HLR] Fix project installation to copy only required files #1

@sgbett

Description

@sgbett

Problem

The install-framework.sh script uses cp -r .architecture/.architecture/.architecture/* .architecture/ which blindly copies the entire .architecture/ directory from the cloned repo — including 40+ framework-internal files (11 ADRs, 10 reviews, 8 comparisons, research docs, a 50KB deferrals.md, methodology documents). These are the framework's own work product and should never appear in a target project.

The MCP server (mcp/index.js) takes a completely different approach — generating everything programmatically with hardcoded templates. Neither approach is correct: blind copy installs cruft, hardcoded generation creates duplication.

Additionally, the triple-nesting clone path (.architecture/.architecture/.architecture/) is confusing and error-prone.

Approach

Manifest-based selective installation:

  1. Clone repo to /tmp (not nested inside .architecture/) with --depth 1
  2. Copy only files listed in a manifest (.install-manifest in repo root)
  3. Create empty directory structure for project-specific content
  4. Initialise config from template
  5. Let the skill's interpretive steps handle content generation (members.yml, principles.md, initial analysis)

What gets copied from repo (templates + agent docs):

  • templates/ directory (9 files: ADR template, review template, config template, etc.)
  • agent_docs/ directory (3 files: progressive disclosure reference docs)

What gets created as empty directories:

  • decisions/adrs/, reviews/, recalibration/, comparisons/

What the skill generates (not the script):

  • members.yml — from scratch based on project analysis
  • principles.md — from scratch based on detected tech stack
  • config.yml — initialised from templates/config.yml
  • reviews/initial-system-analysis.md — from skill's analysis step

Skill instruction changes:

  • Steps 3 & 4: change from "customize" to "create from scratch"
  • Remove assumption that members.yml/principles.md exist before the skill runs

Acceptance Criteria

  • Install script clones to /tmp, not nested inside .architecture/
  • Only manifest-listed files are copied to target project
  • No framework ADRs, reviews, comparisons, or research docs in target project
  • Empty directories created for project-specific content
  • Config initialised from template (not copied from framework's own config)
  • Skill instructions updated: members.yml and principles.md created from scratch
  • .install-manifest checked into repo listing exactly what to copy/create
  • Existing CI tests updated, new tests for manifest-based installation
  • Idempotent: running setup twice doesn't break anything

Context

Metadata

Metadata

Assignees

No one assigned

    Labels

    project:hlrHigh-Level Requirement

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions