icm-workspace-architect
Design, scaffold, audit, and restructure workspaces using Interpretable Context Methodology (ICM, arXiv:2603.16021). Binds folder hierarchy to context scoping (L0-L4), replaces framework code with plain contracts, and validates with the walk test. Do not use for real-time high-concurrency multi-user serving or mid-pipeline dynamic branching.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- icm-workspace-architect
- description
- Design, scaffold, audit, and restructure workspaces using Interpretable Context Methodology (ICM, arXiv:2603.16021). Binds folder hierarchy to context scoping (L0-L4), replaces framework code with plain contracts, and validates with the walk test. Do not use for real-time high-concurrency multi-user serving or mid-pipeline dynamic branching.
02 资源文件 6
- 参考文档CARD.md3.4 KB
- 参考文档config.default.yaml667 B
- 脚本scripts/icm_index.py1.5 KB
- 脚本scripts/icm_links.py2.0 KB
- 脚本scripts/icm_quotes.py2.1 KB
- 脚本scripts/icm_viz.py2.9 KB
03 SKILL.md 正文
ICM Workspace Architect
icm-workspace-architect is the production architecture engine for designing and restructuring workspaces where the folder structure executes agent orchestration. Rooted in the research of Van Clief & McDermott (Interpretable Context Methodology: Folder Structure as Agent Architecture, arXiv:2603.16021), ICM replaces complex multi-agent orchestration frameworks with five-layer context hierarchies, plain markdown contracts, and auditable stage checks.
Every ICM architecture cycle follows a five-stage progression:
[1. Scope & Form Selection] ──► [2. Hierarchy & Contracts] ──► [3. Verification Tooling]
│
▼
[5. Finalization & Maintenance] ◄── [4. 8-Point Cold Walk Test] ◄────┘
See CARD.md for the companion summary card, form taxonomy, and invariants checklist.
Consult /crafting-skills for craft standards and /agent-skill-sdlc for lifecycle validation.
The 10 Mandatory Invariants
- One folder, one job — Each folder performs a single step or holds a single kind of entity, declaring its purpose within itself.
- Small, stable entry file —
AGENTS.mdat root answers "where am I, where does everything live, where do I go for task X" in <60 lines. - Numbering encodes order — Numbered prefixes (
01_,02_) sequence work where order matters. - Every working folder has a contract — A
CONTEXT.mddefining Inputs, Process, Outputs, and Check. - Factory vs. product split — Reference materials (
_shared/, schemas, voice) live apart from working artifacts (output/, records). - Every step ends at a check — Each stage output must pass a verified check (
check.mdwithpassorfail: <why>) before downstream execution. - Load only what the step needs — Step context (entry + contract + references + inputs) must stay under ~8,000 tokens.
- Plain text, linkable, queryable — Markdown + YAML frontmatter with relative links that always resolve.
- Status lives on disk — State is reflected directly in filesystem artifacts and generated
_index.mdfiles. - Instantiate by copying — New work units are copies of templates from
_templates/, never blank pages.
1. Scope & Form Selection
Determine operational mode and select the matching ICM form from the 3 primitives (Sequence, Shelf, Catalog):
- Select Operational Mode:
- Build Mode: Start from an interview or process description. Identify pauses (stage boundaries), invariant rules (factory references), and deliverables.
- Restructure Mode: Take an existing messy folder or repository. Inventory files without moving, classify into 5 roles (
catalog,contract,factory,product,dead), check live referrers, and propose a migration plan.
- Select the Form:
- Pipeline: Sequential production line with handoffs where stage $N$ output is stage $N+1$ input.
- Record Library: Uniform records accumulating status (
_index.mdgenerated from frontmatter). - Knowledge Bundle: Linked concepts, claims, and raw sources with verbatim quote checks.
- Context Map: Organizational graph of teams and processes linked by
consumes:/produces:. - System Map: Codebase audit hierarchy with nouns, verbs, and an impact index.
Completion gate: Mode selected, repeating unit identified, and candidate form confirmed.
2. Hierarchy & Contract Authoring
Scaffold the five-layer context hierarchy (L0–L4) and author stage contracts:
- Scaffold L0 & L1 Catalogs:
- Write root
AGENTS.md(<60 lines) defining identity, routing table, and rules. - Author pointers:
CLAUDE.md(@AGENTS.md) andGEMINI.md(@./AGENTS.md). - Author root
CONTEXT.mdmapping the overall pipeline or shelf schema.
- Write root
- Author L2 Stage Contracts:
- Every working stage receives a
CONTEXT.md:## Inputs: Backticked exact paths partitioned intoWorking (this run)andReference (every run).- Explicit
Do NOT load:statement deflecting irrelevant folders. ## Process: Numbered, deterministic instructions (commands named explicitly).## Outputs: Specific file paths inoutput/.## Check: Concrete check by person, script, or small model emittingcheck.md.
- Every working stage receives a
- Scaffold L3 Factory & Templates:
- Stable reference material in
_shared/voice.mdor_meta/schema.md. - Stamp templates in
_templates/.
- Stable reference material in
Completion gate: L0–L4 hierarchy scaffolded; contracts carry inputs, process, outputs, and checks.
3. Verification & Guardrail Tooling
Deploy deterministic standard-library verification scripts into the workspace's _tools/ or execute via Harness CLI:
- Link & Input Verification (
icm_links.py):- Verify that every markdown link, frontmatter
.mdpath, pointer import, and backticked contract input resolves cleanly:harness icm links .
- Verify that every markdown link, frontmatter
- Frontmatter Index Generation (
icm_index.py):- Rebuild
_index.mdfiles across record folders from frontmatter metadata without hand-editing:harness icm index records
- Rebuild
- Quote & Provenance Verification (
icm_quotes.py):- For knowledge bundles, verify verbatim quote matches against
sources/raw/and enforce_meta/keep-out.txt:harness icm quotes .
- For knowledge bundles, verify verbatim quote matches against
Completion gate: Verification scripts installed in
_tools/or CLI verified; zero broken links.
4. The 8-Point Cold Walk Test
Walk the workspace cold as an agent with zero memory to ensure interpretability:
- Where am I: Can the agent answer its task location within
AGENTS.mdplus at most 2 reads? - Exact Inputs: Does the active stage contract list exact, verifiable input paths?
- Pure Disk Status: Can system status be determined entirely from disk files and
check.mdverdicts? - No Content in Catalog: Are routing files (
AGENTS.md,CONTEXT.md) free of content payloads? - Single Source of Truth: Does each fact live in exactly one home, linked rather than duplicated?
- Resolving Links: Does
harness icm links .pass with zero broken references? - Token Budget Under 8k: Does contract + references + inputs remain strictly under 8,000 tokens?
- Broken Invariants Explained: If an invariant is broken on purpose, is the reason documented?
Completion gate: All 8 points of the cold walk test confirmed passing.
5. Artifact Finalization & Maintenance
Harden and maintain the working ICM workspace:
- Audit Compliance:
- Run the comprehensive audit command:
harness icm audit . --json - Assert all 10 mandatory invariants pass with zero error-severity violations.
- Run the comprehensive audit command:
- Continuous Hardening:
- Fold stages that no longer require human checks.
- Script checks that never fail to eliminate manual bottlenecks.
- Split contracts that grow beyond the 8,000 token ceiling.
Completion gate: Audit passes clean; workspace operational and documented.
The Visual Brief Pillar
Every ICM design or restructuring session must generate an interactive, self-contained HTML visual brief:
- Target File Location: Write to
%TEMP%\\icm-architect-visual-brief-<timestamp>.html(Windows) or/tmp/icm-architect-visual-brief-<timestamp>.html(Unix). - Visual Standards: Dark theme (
#0d1117), Tailwind CSS, and Mermaid.js via CDN. Display the 5-layer hierarchy DAG, the 4-axis repository matrix, and the 10 invariants scorecard. - Delivery: Surface the clickable file path to the user before workspace mutation.
Mandatory Checkpoint Pillar
Prevent premature execution and unreviewed state mutations:
- Present draft
implementation_plan.mddetailing target form, folder hierarchy, contracts, and migration maps. - Set
RequestFeedback: truein artifact metadata. - STOP and wait for explicit user review and approval before creating or modifying workspace files.
Anti-Patterns
- Orchestration Code Sprawl — Writing complex Python multi-agent orchestration frameworks where simple numbered folders and plain files suffice.
- Bloated Routing Catalogs — Stuffing background explanations and domain essays into
AGENTS.mdinstead of keeping it strictly under 60 lines. - Unchecked Stage Handoffs — Allowing pipeline execution to proceed without a verified human or automated
check.mdverdict. - Context Flooding — Loading the entire workspace context into agent prompts instead of scoping strictly to the current stage (<8,000 tokens).
- Hand-Edited Indexes — Manually maintaining record summaries in
_index.mdinstead of generating them deterministically from frontmatter. - Blind Restructuring — Moving or deleting files in an existing codebase without mapping live external referrers first.
- Duplicated Reference Truths — Copying style guides or schemas into every stage folder instead of referencing a single home in
_shared/. - Untracked Case Collisions — Renaming files to
CONTEXT.mdon case-insensitive filesystems without checking for existingcontext.mdfiles.
04 同仓库更多 Skills
ui-behavior-primitive-architect
Architect, audit, and verify zero-dependency headless UI behavior primitives, WebMCP agent bridges, WAI-ARIA/SSR/RTL tri-modal checks, and framework expert routing. Do not use for static CSS theme styling or backend database migrations.
trustgraph-ontology-governor
Govern knowledge graphs, SHACL-AF triple policies, OntologyRAG subclass validation, PROV-O dual named graphs, and Laya entropy decision scoring. Do not use for relational SQL queries or generic web scraping.
shim-harness-governor
Govern universal CLI agent loops, 4-tier tool permissions, ancestor-symlink workspace sandboxes, deterministic-first command routing, collision-safe MCP namespacing, and layered skill loading. Do not use for static UI styling or external SQL analytics.
graphiti-zep-memory-governor
Govern bi-temporal knowledge graphs with Graphiti future-edge clamping, MinHash/LSH entity dedup, RRF/MMR reranking, and Zep typed ontologies. Do not use for static SQL joins or generic web crawling.
agora-mcp-workbench-architect
Architect, audit, and orchestrate Agora Workbench MCP servers, loopback sidecars, unified state graphs, gateway/dispatcher connectors, and policy-enforced data lakes. Do not use for static frontend CSS styling or non-MCP desktop GUI automation.
skill-eval-assurance-runner
Evaluate and assure agent skills using small-N Wilson confidence intervals, unbiased pass^k reliability, deterministic trajectory graders, preflight boundary honesty, and sealed digest verification. Do not use for subjective prose review or unconstrained production deployment.