{
  "markdown": "# Linear Project Skills\n\nThree interoperable Agent Skills and an optional MCP server for creating, maintaining, and reconciling Linear projects without pulling unrelated work into scope.\n\nThis collection is an [Openly Useful](https://openlyuseful.org) project: practical infrastructure people can inspect, adapt, and improve.\n\nOpenly Useful LLC is the planned legal entity and remains `formation-pending`. Openly Useful is currently operated by its founder as an individual, and this repository does not claim that the LLC is formed, active, or the current operator. [`publisher.json`](publisher.json) is a repo-local projection of the [public publisher authority](https://openlyuseful.org/publisher/manifest.json). The founder-owner has authorized external source and registry publication while formation proceeds; namespace verification, provider authentication, and provider review remain provider-specific steps.\n\n## Included skills\n\n| Skill | Use it to |\n| --- | --- |\n| [`linear-bootstrap-scoped-project`](skills/linear-bootstrap-scoped-project/SKILL.md) | Create a net-new project, establish the key-bearing team, link canonical sources, and import legacy work safely. |\n| [`linear-sync-project-work`](skills/linear-sync-project-work/SKILL.md) | Keep implementation evidence, backlog gaps, blockers, and status current while work proceeds. |\n| [`linear-reconcile-project-history`](skills/linear-reconcile-project-history/SKILL.md) | Find an existing project, move high-confidence related issues, and capture legacy evidence as `[HISTORICAL]`. |\n\nThe skills hand work to one another rather than duplicating responsibilities:\n\n```text\nnew project ──> bootstrap ──> sync\n                    ▲\n                    │ no canonical project\nexisting work ─> reconcile ──> sync\n```\n\n## Optional MCP server\n\n[`@openly-useful/linear-project-mcp-server`](mcp/linear-project-mcp-server/README.md) turns the workflows into 13 typed MCP tools. It can create a dedicated Linear team or subteam, bootstrap a scope-labeled project, capture active or `[HISTORICAL]` issues idempotently, find and explicitly move reviewed reconciliation candidates, and link verified evidence.\n\nThe server calls Linear directly through its official TypeScript SDK. GitHub evidence is optional and read-only. Obsidian support is optional, local, restricted to allowlisted Markdown directories, and never copies note contents into Linear when adding a link.\n\nAll mutations are disabled by default and require an exact organization allowlist, a scope-code allowlist, team/project gates, and a literal per-tool confirmation. See the [server setup and security guide](mcp/linear-project-mcp-server/README.md) for installation and client configuration.\n\nThe MCP integration has four intentionally distinct names:\n\n| Name | Meaning |\n| --- | --- |\n| `linear_project` | Canonical Codex MCP registration alias and the name used with `codex mcp` commands. |\n| `@openly-useful/linear-project-mcp-server` | npm package name. It becomes installable from npm after the first successful package release. |\n| `linear-project-mcp-server` | Package executable and MCP protocol server artifact name. |\n| `linear-project-mcp-write-window` | Package helper for explicitly opening, inspecting, and closing a bounded write window. |\n\nFor a source checkout, build the package and register the local executable with Codex:\n\n```sh\ncd mcp/linear-project-mcp-server\npnpm install --frozen-lockfile\npnpm build\nMCP_ENTRYPOINT=\"$(pwd)/dist/index.js\"\ncodex mcp add linear_project -- node \"$MCP_ENTRYPOINT\"\ncodex mcp get linear_project --json\ncodex mcp list --json\n```\n\nThese commands contain no credentials. Supply adapter credentials through a protected launcher or secret store rather than command arguments or committed client configuration. See the [MCP client guide](mcp/linear-project-mcp-server/README.md#connect-codex) for the npm command that applies after the first release and for the expected read-only acceptance checks.\n\n## The key rule\n\nLinear issue identifiers inherit their prefix from a **team**, not a project or label. A workflow that must begin at `XY-1` therefore needs a new team with key `XY`, a verified empty issue history, and immediate readback of the first created issue. These skills stop instead of pretending that a project label can provide that guarantee.\n\n## Install\n\nClone the repository, then copy the skills you want into the user-level skills directory supported by your agent.\n\nFor Codex:\n\n```sh\ngit clone https://github.com/Openly-Useful/linear-project-skills.git\ncp -R linear-project-skills/skills/linear-bootstrap-scoped-project ~/.codex/skills/\ncp -R linear-project-skills/skills/linear-sync-project-work ~/.codex/skills/\ncp -R linear-project-skills/skills/linear-reconcile-project-history ~/.codex/skills/\n```\n\nStart a new task or restart the agent if its skill catalog does not refresh automatically.\n\n## Provider registration artifacts\n\nThe repository root is one aggregate plugin containing all three canonical skill directories. [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json) and [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json) both point to `./skills/` and [`.mcp.json`](.mcp.json); no provider-specific skill copies or symlinks are maintained. The MCP config uses `npx`/`npm exec` to install the immutable `@openly-useful/linear-project-mcp-server@0.1.0` package and launch its server entry explicitly. This avoids ever selecting the package's separate write-window helper and remains portable across host shells. Repo-local Codex and Claude marketplace catalogs point back to the repository root for the same reason.\n\nRegistration files are generated from [`manifest.json`](manifest.json), [`publisher.json`](publisher.json), and the MCP package metadata:\n\n```sh\npython3 scripts/sync_registration.py --check\npython3 scripts/sync_registration.py --write\n```\n\nThe write form changes only repo-local registration files. It does not install a plugin, add a marketplace to a host, authenticate, publish a package, submit an MCP Registry record, or change the founder-authorization gate.\n\nAfter installing or upgrading the plugin, start a new Codex task or restart Claude Code so the host discovers the newly registered MCP tools. The plugin never embeds credentials or scope values. Supply `LINEAR_API_KEY` or `LINEAR_ACCESS_TOKEN` and the exact `LINEAR_ALLOWED_*` settings through the host environment or a protected launcher. Without them the server still starts, writes remain disabled, and Linear tools fail closed with configuration guidance.\n\nThe MCP Registry record is [`mcp/linear-project-mcp-server/server.json`](mcp/linear-project-mcp-server/server.json). Its registry identity is `org.openlyuseful/linear-project`, while its npm package remains `@openly-useful/linear-project-mcp-server`. The official Registry requires `server.json.name` and `package.json.mcpName` to match; the repository validator enforces that equality together with package and version alignment.\n\n## Requirements\n\n- An agent runtime that supports the Agent Skills directory format.\n- A connected Linear integration with permission to read the target workspace and perform the requested writes.\n- Access to linked repositories or local project sources when those sources are part of the requested scope.\n- A workspace administrator when a new Linear team or team key must be provisioned and the integration cannot create one.\n- Node.js 20 or newer only when using the optional MCP server.\n\nThe skills do not include credentials, a background daemon, or permission to monitor or mutate unrelated projects.\n\n## Example prompts\n\nCreate a project with a dedicated issue sequence:\n\n```text\nUse $linear-bootstrap-scoped-project to create the Atlas project, link its repository,\nuse a new team key ATLS, make the charter ATLS-1, and import the allowlisted legacy work.\n```\n\nKeep current implementation synchronized:\n\n```text\nUse $linear-sync-project-work while implementing this change. Update only the canonical\nproject and label, attach verified evidence, and keep incomplete work out of Done.\n```\n\nReconcile an existing project:\n\n```text\nUse $linear-reconcile-project-history to find the canonical Atlas project, move only\nexact-identity matches, and capture non-Linear legacy evidence as [HISTORICAL].\n```\n\n## Historical records\n\nHistorical capture is deliberately separate from active work. A historical issue:\n\n- begins with `[HISTORICAL]`;\n- carries the project-code and `HISTORICAL` labels;\n- records stable source identity and capture time;\n- states `Historical only: true` and `Actionability: none`;\n- does not claim current completion, ownership, authorization, or validity;\n- is deduplicated by a deterministic source marker.\n\n## Safety model\n\nEvery workflow is read-first and scope-gated:\n\n- resolve one canonical destination before writing;\n- use allowlisted teams, labels, repositories, and source containers;\n- treat fuzzy matches as evidence for review, not authority to move work;\n- preserve team identifiers unless an identifier-changing move is explicitly authorized;\n- never infer Done from a commit, closed source item, or agent assertion alone;\n- read back every mutation and reconcile expected versus actual counts;\n- require a zero-write second pass after a historical sweep.\n\n## Validate\n\nThe repository validator uses only the Python standard library:\n\n```sh\npython3 scripts/test_validate.py\npython3 scripts/validate.py\npython3 scripts/sync_registration.py --check\n```\n\nTo validate the MCP server too:\n\n```sh\ncd mcp/linear-project-mcp-server\npnpm install --frozen-lockfile\npnpm check\npnpm pack --dry-run\n```\n\nThe repository validator checks skill structure, metadata, references, manifest entries, MCP package metadata, evaluations, placeholder text, and common private-data leaks. Pull requests run both validation paths in GitHub Actions. The MCP compatibility job runs the full server check on Node.js 20, 22, and 24; distribution validation runs once, and package-content inspection runs only on Node.js 24.\n\n`python3 scripts/validate.py --external-publication --publication-target npm-package` checks the founder-owner authorization plus the exact publisher identity, policy URLs, namespace, repository provenance, package identity, and registry metadata used by the npm artifact. The MCP package runs that fail-closed gate from `prepublishOnly`. Formation-pending is not itself an npm package blocker because the current operator is the founder-individual and the founder-owner authorization is explicitly effective during formation. Generic provider requirements remain blocking for MCP Registry and provider submissions until their separate workflows are completed.\n\n## Public-data boundary\n\nDo not contribute credentials, private repository content, customer data, local absolute paths, raw conversations, or organization-specific source inventories. Examples must use synthetic names and identifiers. Public source markers should be sanitized and should reveal no secret or personal data.\n\n## Contributing and security\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the repository-specific workflow. Openly Useful's organization-wide [Code of Conduct](https://github.com/Openly-Useful/.github/blob/main/CODE_OF_CONDUCT.md) and [Security Policy](https://github.com/Openly-Useful/.github/blob/main/SECURITY.md) apply.\n\n## License\n\nReleased under the [MIT License](LICENSE).\n",
  "bytes": 11387,
  "sha": "0904a3e50ab96774922707e9f810e9245d03bbe8c10781e3afe746ddd13adda6",
  "repo_slug": "openly-useful/linear-project-skills",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_org_openlyuseful_linear_project_ced40442/readme"
}