cooper

A scaffold installer that gives coding agents (Copilot, Claude Code, Codex, etc.) the structure they need to be useful inside real working environments — persistent memory, studies, knowledge, and skills.

Install

cd /path/to/your-repo
npx @archi-physics/cooper init

This creates a cooper/ directory in your repo with:

• cooper/AGENTS.md — operating instructions every agent reads first
• cooper/knowledge/ — canonical, reusable project knowledge
• cooper/memory/ — working memory, decisions, handoff notes
• cooper/studies/ — per-topic investigations with run logs
• cooper/refs/ — local references (papers, notes, links)
• cooper/skills/ — reusable agent skills/modules

It also adds a managed AGENTS.md block at your repo root that points assistants to the scaffold.

Your project's own code, configs, and scripts stay where they are. Cooper doesn't touch them — it just gives agents the context and structure to help you with them.

Options

• --path <dir>: target repo path (default: current directory)
• --subdir <name>: install subdirectory (default: cooper)
• --force: overwrite existing scaffold files

Update

When a new version of Cooper is released, update your scaffold's infrastructure files (policies, templates) without touching your content (knowledge, studies, decisions):

cd /path/to/your-repo
npx @archi-physics/cooper update

This overwrites infrastructure files (AGENTS.md, study templates, example configs) and preserves user files (knowledge base, memory, studies, refs).

To preview what would change:

npx @archi-physics/cooper update --dry-run

Update Options

• --path <dir>: target repo path (default: current directory)
• --subdir <name>: install subdirectory (default: cooper)
• --force: also overwrite user content files
• --dry-run: show what would change without writing

Why Cooper?

Frontier agents are already highly capable. The bottleneck isn't intelligence — it's context. Agents need local structure to be effective: project docs, workflows, reusable skills, domain knowledge, and a persistent memory of what was done and why.

Cooper provides that scaffold so agents can plug into your environment, follow your way of working, and improve over time through documented history.

What the Scaffold Enforces

• Study discipline: Every investigation gets a study directory with a clear question, tracked pipeline runs, and documented conclusions. Agents must log every run immediately — no batching.
• Session continuity: Agents read memory on startup and update it on handoff, so context persists across sessions.
• Knowledge promotion: Reusable findings get promoted from ephemeral notes into the permanent knowledge base.
• Decision tracking: Every significant decision is logged with rationale, alternatives considered, and reversibility.

See templates/cooper/AGENTS.md for the full policy.

Repository Structure (This Repo)

This is the npm package source, not a working scaffold instance.

cooper/                        # This repo (npm package source)
├── AGENTS.md                  # Instructions for developing Cooper
├── package.json               # npm package definition
├── bin/cooper.js              # CLI entrypoint (cooper init)
├── templates/cooper/          # Scaffold payload installed into user repos
│   ├── AGENTS.md              # Agent operating instructions
│   ├── knowledge/             # domain knowledge base
│   ├── memory/                # session memory & decisions
│   ├── studies/               # tracked investigations
│   ├── refs/                  # references & papers
│   └── skills/                # reusable agent skills
├── openspec/                  # Design specs for Cooper development
│   ├── cooper.md              # Vision, scope, boundaries
│   └── project.md             # Tech stack, conventions
└── README.md

When installed into a user's repo:

their-analysis-repo/
├── AGENTS.md                  # Managed block → points to cooper/
├── their_code/                # User's existing code (untouched)
├── their_configs/             # User's existing configs (untouched)
└── cooper/                    # Installed by `cooper init`
    ├── AGENTS.md              # Agent operating instructions
    ├── knowledge/             # Domain knowledge base
    ├── memory/                # Session memory & decisions
    ├── studies/               # Tracked investigations
    ├── refs/                  # References & papers
    └── skills/                # Reusable agent workflows

Contributing

Development Setup

git clone [email protected]:archi-physics/cooper.git
cd cooper

No build step — the package is plain JS and markdown templates.

Testing Locally

Run a smoke test that installs the scaffold into a temp directory:

npm run test:smoke

To test the CLI against a real repo without publishing:

cd /path/to/test-repo
npx /path/to/cooper init

npm Authentication

You must be logged in to npm with access to the @archi-physics org:

npm login
npm access grant read-write @archi-physics:developers  # if needed

Publishing to npm

1. Ensure you're on main with a clean working tree:

   git checkout main && git pull
   git status  # should be clean

2. Bump the version:

   npm version patch   # or minor / major

   This updates package.json and creates a git tag (v0.1.1, etc.).

3. Push the version commit and tag:

   git push origin main --tags

4. Publish:

   npm publish --access public

Version Policy

• patch (0.1.x): template content changes, bug fixes, doc updates
• minor (0.x.0): new scaffold features (e.g., new directories, CLI flags)
• major (x.0.0): breaking changes to scaffold structure or CLI interface