Run 002 - full-union harness materialization

Run date: 2026-07-13
Environment: Windows, Python 3.14.0, Node 22.21.1
Generated surface: .cache/harborworks-operations-workbench/
Status: Harness-neutral filesystem discovery validated; no named agentic harness was configured.

Question

Can the full resolved Harborworks composition be materialized as one practical filesystem surface with:

one skill-discovery root;

globally unique materialized skill names;

one knowledge root with repository names one level below it;

one tooling root with repository names one level below it; and

working skill references after relocation?

No profiles or scope filters were applied. The materialization is the union of all nine resolved contexts.

Generated layout

.cache/
  harborworks-operations-workbench/
    skills/
      <repository>--<skill>/
        SKILL.md
    knowledge_base/
      <repository>/
        ...
    src/
      <repository>/
        ...
    catalog.json
    composition-summary.json

The composer repository name scopes the generated surface within the shared .cache/. The future .composed/ convention discussed during this investigation was not implemented or specified.

Reproduction

From the repository root:

python .cache\src\harborworks-composition\test_composer.py -v
python .cache\src\harborworks-composition\compose.py materialize --root memory\2026-07\13\harborworks-composition-experiment\fixtures\repos\harborworks-operations-workbench --output .cache\harborworks-operations-workbench

Transformation

The fixture skills were not relocatable without modification. For example, an original domain skill referred to:

../../knowledge_base/overview.md
python src/cli.py --skill inspect-dataset --knowledge knowledge_base/overview.md

Its materialized form refers to:

../../knowledge_base/harborworks-data-governance/overview.md
python src/harborworks-data-governance/cli.py --skill harborworks-data-governance--inspect-dataset --knowledge knowledge_base/harborworks-data-governance/overview.md

The prototype also changed the skill frontmatter name to the stable generated name and added a source-identity comment. It recorded source and materialized digests in catalog.json.

These were controlled textual transformations, not a general Markdown or shell rewriter. The prototype applied five known rewrite classes to every skill:

frontmatter skill name;

Markdown knowledge link;

CLI entrypoint;

CLI skill identity;

CLI knowledge argument and execution-root wording.

The catalog recorded 270 rewrite occurrences across 54 skill documents.

Observations

The materialized file counts were:

54 skills/<repository>--<skill>/SKILL.md files;

18 knowledge_base/<repository>/... files; and

9 src/<repository>/... files.

The five collision groups observed in Run 001 disappeared at the destination because skills were globally prefixed and knowledge/tool paths were repository-namespaced.

Interpretation

The experiment supports a physical, full-union handoff surface. A harness only needs one generated skill root rather than a setting containing every imported skill directory. Repository-prefixing every skill is more stable than renaming only collisions because adding a new repository cannot rename an existing materialized skill.

The experiment also confirms that relocation has a compatibility cost. The current fixtures worked only because their reference patterns were known and rewritable. A future composition convention should either:

restrict composable repositories to declared, relocatable reference forms;

define a stable context-root reference notation; or

classify arbitrary rewriting/wrapping as an explicit compatibility mechanism rather than guaranteed composition behavior.

Limitations

The validation simulated a harness that discovers immediate skills/*/SKILL.md children; it did not configure Codex, Claude Code, VS Code, or another named harness.

The rewrite logic recognizes only the fixture's controlled patterns.

The generated catalog still contains absolute local source paths for all 81 artifacts. A portable standard should use repository source identity and resolved revision, keeping checkout paths as local resolver state.

The Python and Node CLIs are hello-world fixtures and do not themselves read the passed knowledge files; the validator separately checked those files and links before execution.

.cache/<composer-name>/ is an experimental workspace layout. The proposed repository-root .composed/ convention remains an open design choice.