0 Fork 0

mirror of https://github.com/paperclipai/paperclip.git synced 2026-11-13 15:55:46 +01:00

Files

T

DottaandClaude Opus 5.5 9b21dcbdda refactor: remove SPEC docs and repoint spec citations (#20565 )

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Contributors and agents read the docs under `doc/` before they
change code
> - `doc/SPEC.md` and `doc/SPEC-implementation.md` were out of date.
`doc/SPEC-implementation.md` became an append-only log: in 60 days it
got about 1,645 new lines and lost 181, across 140 commits
> - #20557 changed `AGENTS.md` so the code and its tests are the source
of truth, and the specs are only background
> - This pull request removes the two spec docs. It moves only the
sections that live code comments cite into focused docs, and it repoints
all other references
> - The benefit is one less stale document that agents read and append
to

## Linked Issues or Issue Description

Refs #20557 (merged). This PR is the follow-up that removes the docs. It
is based on `master`, which already contains #20557.

**Issue type**
Outdated content. The docs are out of date and conflict with the code.

**Where is the issue?**
`doc/SPEC.md`, `doc/SPEC-implementation.md`, and the code comments and
docs that cite them.

**What's wrong?**
`doc/SPEC.md` and `doc/SPEC-implementation.md` are out of date, but
agents still read them and append a paragraph with each fix.

**Suggested fix**
Delete both files. Move the sections that code cites into focused docs.
Repoint the references.

## What Changed

- Deleted `doc/SPEC.md` and `doc/SPEC-implementation.md`.
- Moved these spec sections, because live code comments cite them:
- §9.3.1 "Shared default-open issue writes" → new section in
`doc/agent-permission-defaults.md`.
- §9.8.1 "Issue-thread interaction resolver contract" →
`doc/execution-semantics.md`, "Issue-thread interaction resolution".
That section already had most of the contract. I added only the missing
parts: the `supersedeOnUserComment` default, the canonical policy list,
the addressee and cap rules, the rule that surfaces show the server's
effective audience, and the cross-issue budget charge. The short policy
summary at the top of the section now points to the list, so the
definitions occur one time only.
- §9.9 "Task Watchdog Authority Contract" → new "Authority contract"
section in `doc/TASK-WATCHDOG.md`. It holds the allowed and disallowed
mutation lists and the deferred capabilities. The atomic recovery batch,
restoration verification, and interaction rules were already in
`doc/execution-semantics.md` §11, so the new section links there and
does not repeat them. I did not move the "Downstream acceptance
criteria" checklist or the sentence about the CTO and Security sign-off.
These were implementation-time notes; the tests now hold that coverage.
- §9.10 "Company Skill Policy Contract" → new
`doc/company-skill-policy.md`. No focused doc had this contract. I did
not move the "Required regression tests" phase checklist.
- Did not move any other part of the specs.
- Repointed code comments that cited spec sections:
- `packages/shared/src/issue-write-denial.ts` (§9.3) →
`doc/agent-permission-defaults.md`
- `server/src/routes/issues.ts` (§9.9) → `doc/TASK-WATCHDOG.md`,
"Authority contract"
- `server/src/routes/issues.ts` (§9.3, §9.8.1 cross-issue budget) →
`doc/agent-permission-defaults.md`
- `ui/src/lib/interaction-audience.ts` and
`ui/src/components/InteractionGovernancePanel.tsx` (§9.8.1) →
`doc/execution-semantics.md`
- `ui/src/lib/skill-policy-denial.ts`, `ui/src/pages/CompanySkills.tsx`,
`ui/src/pages/CompanySkills.production.tsx`,
`ui/src/pages/SkillStudio.tsx` (§9.10) → `doc/company-skill-policy.md`
- `server/src/services/recovery/ownership-invariant-report.ts` (monitor
deadline wait path) → `doc/execution-semantics.md` §8. That section
already lists the one-shot monitor as a valid wait path.
- Resynced the git blob pin for
`packages/shared/src/issue-write-denial.ts` in
`tests/runner-e2e/source-sdk-public-inputs.json`. The comment edit
changed the file's hash, and the Runner support suite checks that pin. I
used `node tests/runner-e2e/source-sdk-public-inputs.mjs <HEAD>
--write`; only that one pin changed.
- Updated `AGENTS.md` §1 so it does not name the deleted files.
- Removed the links to the deleted files from
`doc/plugins/PLUGIN_SPEC.md`.
- Updated the `doc-maintenance` agent skill
(`.agents/skills/doc-maintenance/`) so it no longer audits or stages
`doc/SPEC.md`.
- Removed or replaced references in `maps/README.md`,
`maps/feature-map/README.md`, `maps/storybook-map/README.md`,
`doc/PRODUCT.md`, `doc/CLIPHUB.md`, `doc/DEPLOYMENT-MODES.md`,
`doc/DEVELOPING.md`, `doc/evals.md`, `doc/spec/agent-runs.md`,
`doc/AGENTCOMPANIES_SPEC_INVENTORY.md`,
`doc/connections/CONNECTOR-PLAYBOOK.md`,
`doc/plugins/ideas-from-opencode.md`, `doc/execution-semantics.md`,
`doc/TASK-WATCHDOG.md`, and `.devin/wiki.json`.
- In `doc/execution-semantics.md`, the "admission is independent of
cleanup and accounting" reference now states the rule inline: only a
hard stop, an explicit pause, or an inactive company refuses admission.
- Kept these references as they are: dated plans in `doc/plans/` and
`docs/plans/`, the dated log
`doc/logs/2026-05-24-cli-api-parity-e2e-log.md`, `releases/`, the
transcript fixture `ui/src/fixtures/runTranscriptFixtures.ts` (it uses
the filename only as sample text), and
`docs/specs/external-task-protocol.md` (it refers to the Symphony
project's own `SPEC.md`).

## Verification

- `git grep -n "SPEC-implementation\|SPEC\.md"` (without `releases/`,
and ignoring `PLUGIN_SPEC.md` citations) finds only the kept references
listed above.
- `grep -rn "§9\.\(3\|8\|9\|10\)" ui/src server/src packages/shared/src`
finds no results.
- `node scripts/check-maps.mjs`: "Maps aligned: 35 areas, 192 capability
IDs".
- `pnpm check:token-gates`: "All gates clean".
- `pnpm exec vitest run --config tests/runner-e2e/vitest.config.ts
tests/runner-e2e/source-sdk-public-type.test.ts
tests/runner-e2e/source-sdk-evidence.test.ts`: 45 passed. These failed
in CI before the pin resync.
- `pnpm verify`: exit 2 ("Broader verification required") because
`AGENTS.md` is a global CI input. Required CI supplies the broad
coverage for this revision.
- All code changes are comments only. No runtime behavior changes. The
title uses `refactor:` because comments in source files changed.

## Risks

- Low risk. The change removes docs and edits comments only.
- A reader can lose context from spec sections that I did not move. The
text stays in git history. The code and its tests are the source of
truth.
- External links to the two deleted files will return 404.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), in Claude Code with
tool use (shell, file edits). Standard context window.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass (focused checks above; CI
supplies broad coverage)
- [x] I have added or updated tests where applicable (not applicable:
docs and comments only)
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [ ] All Paperclip CI gates are green
- [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

2026-11-10 13:07:59 -06:00

7.6 KiB

Raw Blame History

Agent Companies Spec Inventory

This document indexes every part of the Paperclip codebase that touches the Agent Companies Specification (agentcompanies/v1-draft).

Use it when you need to:

Update the spec — know which implementation code must change in lockstep.
Change code that involves the spec — find all related files quickly.
Keep things aligned — audit whether implementation matches the spec.

1. Specification & Design Documents

File	Role
`docs/companies/companies-spec.md`	Normative spec — defines the markdown-first package format (COMPANY.md, TEAM.md, AGENTS.md, PROJECT.md, TASK.md, SKILL.md), reserved files, frontmatter schemas, and vendor extension conventions (`.paperclip.yaml`).
`doc/plans/2026-03-13-company-import-export-v2.md`	Implementation plan for the markdown-first package model cutover — phases, API changes, UI plan, and rollout strategy.
`docs/specs/cliphub-plan.md`	Earlier blueprint bundle plan; partially superseded by the markdown-first spec (noted in the v2 plan).
`doc/plans/2026-02-16-module-system.md`	Module system plan; JSON-only company template sections superseded by the markdown-first model.
`doc/plans/2026-03-14-skills-ui-product-plan.md`	Skills UI plan; references portable skill files and `.paperclip.yaml`.
`doc/plans/2026-03-14-adapter-skill-sync-rollout.md`	Adapter skill sync rollout; companion to the v2 import/export plan.

2. Shared Types & Validators

These define the contract between server, CLI, and UI.

File	What it defines
`packages/shared/src/types/company-portability.ts`	TypeScript interfaces: `CompanyPortabilityManifest`, `CompanyPortabilityFileEntry`, `CompanyPortabilityEnvInput`, export/import/preview request and result types, manifest entry types for agents, skills, projects, issues, recurring routines, companies.
`packages/shared/src/validators/company-portability.ts`	Zod schemas for all portability request/response shapes — used by both server routes and CLI.
`packages/shared/src/types/index.ts`	Re-exports portability types.
`packages/shared/src/validators/index.ts`	Re-exports portability validators.

3. Server — Services

File	Responsibility
`server/src/services/company-portability.ts`	Core portability service. Export (manifest generation, markdown file emission, `.paperclip.yaml` sidecars), import (graph resolution, collision handling, entity creation), preview (planned-action summary). Handles skill key derivation, recurring task <-> routine mapping, legacy recurrence migration, and package README generation. References `agentcompanies/v1` version string.
`server/src/services/routines.ts`	Paperclip routine runtime service. Portability now exports routines as recurring `TASK.md` entries and imports recurring tasks back through this service.
`server/src/services/company-export-readme.ts`	Generates `README.md` and Mermaid org-chart for exported company packages.
`server/src/services/index.ts`	Re-exports `companyPortabilityService`.

4. Server — Routes

File	Endpoints
`server/src/routes/companies.ts`	`POST /api/companies/:companyId/export` — legacy export bundle `POST /api/companies/:companyId/exports/preview` — export preview `POST /api/companies/:companyId/exports` — export package `POST /api/companies/import/preview` — import preview `POST /api/companies/import` — perform import

Route registration lives in server/src/app.ts via companyRoutes(db, storage).

5. Server — Tests

File	Coverage
`server/src/__tests__/company-portability.test.ts`	Unit tests for the portability service (export, import, preview, manifest shape, `agentcompanies/v1` version).
`server/src/__tests__/company-portability-routes.test.ts`	Integration tests for the portability HTTP endpoints.

6. CLI

File Commands

cli/src/commands/client/company.ts company export — exports a company package to disk (flags: --out, --include, --projects, --issues, --projectIssues).
company import <fromPathOrUrl> — imports a company package from a file or folder (flags: positional source path/URL or GitHub shorthand, --include, --target, --companyId, --newCompanyName, --agents, --collision, --ref, --dryRun).
Reads/writes portable file entries and handles .paperclip.yaml filtering.

File	Commands
`cli/src/commands/client/company.ts`	`company export` — exports a company package to disk (flags: `--out`, `--include`, `--projects`, `--issues`, `--projectIssues`). `company import <fromPathOrUrl>` — imports a company package from a file or folder (flags: positional source path/URL or GitHub shorthand, `--include`, `--target`, `--companyId`, `--newCompanyName`, `--agents`, `--collision`, `--ref`, `--dryRun`). Reads/writes portable file entries and handles `.paperclip.yaml` filtering.

7. UI — Pages

File	Role
`ui/src/pages/CompanyExport.tsx`	Export UI: preview, manifest display, file tree visualization, ZIP archive creation and download. Filters `.paperclip.yaml` based on selection. Shows manifest and README in editor.
`ui/src/pages/CompanyImport.tsx`	Import UI: source input (upload/folder/GitHub URL/generic URL), ZIP reading, preview pane with dependency tree, entity selection checkboxes, trust/licensing warnings, secrets requirements, collision strategy, adapter config.

8. UI — Components

File	Role
`ui/src/components/PackageFileTree.tsx`	Reusable file tree component for both import and export. Builds tree from `CompanyPortabilityFileEntry` items, parses frontmatter, shows action indicators (create/update/skip), and maps frontmatter field labels.

9. UI — Libraries

File	Role
`ui/src/lib/portable-files.ts`	Helpers for portable file entries: `getPortableFileText`, `getPortableFileDataUrl`, `getPortableFileContentType`, `isPortableImageFile`.
`ui/src/lib/zip.ts`	ZIP archive creation (`createZipArchive`) and reading (`readZipArchive`) — implements ZIP format from scratch for company packages. CRC32, DOS date/time encoding.
`ui/src/lib/zip.test.ts`	Tests for ZIP utilities; exercises round-trip with portability file entries and `.paperclip.yaml` content.

10. UI — API Client

File	Functions
`ui/src/api/companies.ts`	`companiesApi.exportBundle`, `companiesApi.exportPreview`, `companiesApi.exportPackage`, `companiesApi.importPreview`, `companiesApi.importBundle` — typed fetch wrappers for the portability endpoints.

11. Skills & Agent Instructions

File	Relevance
`skills/paperclip/references/company-skills.md`	Reference doc for company skill library workflow — install, inspect, update, assign. Skill packages are a subset of the agent companies spec.
`server/src/services/company-skills.ts`	Company skill management service — handles SKILL.md-based imports and company-level skill library.
`server/src/services/agent-instructions.ts`	Agent instructions service — resolves AGENTS.md paths for agent instruction loading.

12. Quick Cross-Reference by Spec Concept

Spec concept	Primary implementation files
`COMPANY.md` frontmatter & body	`company-portability.ts` (export emitter + import parser)
`AGENTS.md` frontmatter & body	`company-portability.ts`, `agent-instructions.ts`
`PROJECT.md` frontmatter & body	`company-portability.ts`
`TASK.md` frontmatter & body	`company-portability.ts`
`SKILL.md` packages	`company-portability.ts`, `company-skills.ts`
`.paperclip.yaml` vendor sidecar	`company-portability.ts`, `routines.ts`, `CompanyExport.tsx`, `company.ts` (CLI)
`manifest.json`	`company-portability.ts` (generation), shared types (schema)
ZIP package format	`zip.ts` (UI), `company.ts` (CLI file I/O)
Collision resolution	`company-portability.ts` (server), `CompanyImport.tsx` (UI)
Env/secrets declarations	shared types (`CompanyPortabilityEnvInput`), `CompanyImport.tsx` (UI)
README + org chart	`company-export-readme.ts`

7.6 KiB Raw Blame History