Set up a new project

This is the procedural how-to for setting up a new project that plugs into the Tapestry platform. Follow it top to bottom in a fresh repo and you’ll have the full discipline stack wired correctly from day one.

For the concepts behind these steps, read The discipline stack first. For recovery from failures, see Recover from common failures.

Prerequisites

• Claude Code installed and working.
• node available (for plugin marketplace install).
• The tapestry marketplace added to your Claude Code: /plugin marketplace add Lizo-RoadTown/tapestry. Confirm by running /plugin marketplace list.
• (Optional, recommended) tapestry marketplace too, if you’ll use the patterns plugin: /plugin marketplace add Lizo-RoadTown/tapestry.

Step 1 — Pick a stable project ID

The project ID becomes the LOOM_PROJECT_ID env var, the directory name under .project-intelligence/, and the tag on every memory you write.

Conventions:

• kebab-case
• Append -dev if you anticipate spawning an -app instance later (a separate Claude Code agent for a deployed user-facing surface). One existing example consuming project uses this pattern: a -dev ID for the research/developer-facing instance and a planned -app ID for the eventual user-facing app.
• Single-instance projects don’t need the suffix.

Examples: example-project-dev, summer-2026-hub, your-project-dev.

Step 2 — Install the tapestry-discipline plugin

In any Claude Code session:

/plugin marketplace add Lizo-RoadTown/tapestry
/plugin install tapestry-discipline@tapestry

This installs to your machine’s plugin cache at ~/.claude/plugins/cache/tapestry/tapestry-discipline/<version>/. It is now AVAILABLE on your machine. It is NOT YET enabled in any specific project.

Step 3 — Enable the plugin in your project’s .claude/settings.json

Create .claude/ directory in your project root if it doesn’t exist. Then write .claude/settings.json:

{
  "enabledPlugins": {
    "tapestry-discipline@tapestry": true
  }
}

If you have a per-project guard plugin you also want enabled (e.g., a SDE-style guard), add it alongside:

{
  "enabledPlugins": {
    "tapestry-discipline@tapestry": true,
    "your-guard@your-marketplace": true
  }
}

.claude/settings.json is shared (commit it). .claude/settings.local.json is local-only (gitignored by default in most setups).

Step 4 — (Optional) Add loom-memory MCP to .mcp.json as defense-in-depth

The tapestry-discipline plugin already declares the loom-memory MCP, so enabling the plugin is sufficient to wire it. Adding it explicitly to your project’s .mcp.json is belt-and-suspenders. If the plugin ever fails to load (cache staleness, version mismatch), the MCP tools remain available.

Create or extend .mcp.json at your project root:

{
  "mcpServers": {
    "loom-memory": {
      "type": "http",
      "url": "https://your-memory-host.example.com/mcp/memory/"
    }
  }
}

If you have other MCP servers (Supabase, Render, project-specific ones), declare them alongside loom-memory.

.mcp.json is typically gitignored if it contains secrets (e.g., API tokens in headers). If it only contains URLs, it can be committed.

Step 5 — Set LOOM_PROJECT_ID in .env

Create .env at your project root with at minimum:

LOOM_PROJECT_ID=your-project-id

If you want OTel telemetry to flow to the same Grafana stack as the other projects on this platform, copy the OTel block from an existing project’s .env (the platform operator can share these). Same applies for OPENAI_API_KEY and any other shared credentials.

.env MUST be in .gitignore. Confirm before any commit.

Step 6 — Create .project-intelligence/<project-id>/

This directory holds the per-project agent configuration. Minimal v1 structure:

.project-intelligence/
  <project-id>/
    agent-profile.json
    project-context.json
    observatory-config.json

Templates:

agent-profile.json

{
  "role": "researcher | developer | operator",
  "memory_tag": ["your-project-id"],
  "discipline_rules": [
    "PROBE before asserting",
    "Cite file:line for claims",
    "Save corrections as feedback memory immediately"
  ]
}

project-context.json

{
  "project_id": "your-project-id",
  "purpose": "One sentence on what this project is.",
  "audience": "Who uses its outputs.",
  "stage": "research | building | maintaining"
}

observatory-config.json

{
  "log_events": ["git_action", "memory_write", "skill_invocation"],
  "candidate_triggers": ["3+ similar task executions", "operator says 'we keep doing X'"]
}

For working examples of these JSON configs, see an example consuming project’s .project-intelligence/ directory on GitHub.

Step 7 — Add architecture-snapshot wrappers (recommended)

The tapestry-discipline plugin’s SessionStart hook can run scripts/architecture_snapshot.py and scripts/architecture_diff.py to capture a structural snapshot at session start. These don’t need to be your code — they can be thin wrappers that dispatch to the canonical implementations in the tapestry-patterns plugin.

See the wrapper-pattern reference (consuming project PR) for the canonical example.

If you skip this step, the SessionStart hook silently no-ops on the snapshot piece — the agent loses the architecture context at session start but otherwise works.

Step 8 — Write a CLAUDE.md at the project root

This is the per-project context Claude Code auto-loads. It should explain:

• What this project IS (one paragraph).
• Who the agent IS in this project (researcher / developer / operator).
• Memory hierarchy (point at the loom-memory MCP).
• Where to read (skills, docs, .project-intelligence).
• Discipline rules (restate the ones the plugin enforces, for clarity).
• Token discipline conventions.
• Tone.

See an example consuming project’s CLAUDE.md for a worked example.

Step 9 — Register with the Project Registry (when it’s live)

The Tapestry platform includes a Project Registry service that tracks every consuming project. Registering means future cross-project queries (which projects are using skill X? which projects opted into observability lane Y?) can find your project.

The registry endpoint is https://your-project-registry-host.example.com/projects (currently hosted from the platform’s beta repo; the URL will change when the service migrates into Tapestry — env-var overrides are wired so consuming projects won’t have to chase the rename).

When the registry has its public CLI (tapestry init), one command will do all of this. Until then, a curl POST to register is the manual step. See the Tapestry MASTER_CHECKLIST for current status.

Step 10 — Restart Claude Code and verify

Plugin hooks bind at session start. To pick up the new plugin enable + MCP wiring, you must fully restart Claude Code in this repo (close the IDE window for this project; reopen). /plugin update does NOT hot-swap hooks.

After restart, you should see:

1. A SessionStart auto-recall block at the start of the conversation, with relevant memories tagged for your project.
2. A discipline reminder line at the top of every one of your messages: [loom-discipline] Discipline check: PROBE files before asserting (cite file:line). Distinguish dev-tooling from runtime ...
3. memory_recall, memory_write, etc. available when you ask the agent to use them.
4. If you ask the agent “check loom memory for what we did last session in this project,” it actually does it.

If any of these don’t appear, see Recover from common failures — the symptom-to-fix table covers each one.

What you DON’T need to do

• You don’t need to clone the platform repos to build your project. Your project is a CONSUMER of the platform, not part of it.
• You don’t need to write your own discipline plugin unless you need project-specific guards beyond the general discipline.
• You don’t need to set up your own memory store. The hosted loom-memory MCP serves all consuming projects.
• You don’t need to put architecture-snapshot CODE in your repo — just the thin wrapper scripts that dispatch to the canonical scripts in tapestry-patterns.

The point of the platform is that the heavy infrastructure is deployed once — your own backend — and consuming projects get the benefits with a small wiring layer per project.