Linear Agentic Kit

Reference repository for agent operating standards and reusable templates.

This repo is intentionally markdown-first. It is designed to be read by agents and then applied to a target repository.

It now also ships an optional WORKFLOW.md template so downstream repos can express the same operating contract in a single repo-owned file for daemonized runners such as Symphony or similar orchestrators. The template is intentionally conservative: placeholder-based, low-concurrency by default, and explicit about keeping runtime config aligned with AGENTS.md and docs/agent/*.

User experience target

Humans should be able to run this pattern with short prompts:

• linear-plan <feature I want to plan>
• linear-implement <ISSUE-ID>
• linear-review <ISSUE-ID>
• remind me

The agent is expected to ask clarification questions when needed, instead of requiring humans to provide long structured briefs.

linear-implement is the unified execution entrypoint. The agent chooses direct execution or orchestration mode based on ticket structure.

How to use this kit in another repo

Give your agent this instruction:

Read https://github.com/Mitri45/linear-agentic-kit/blob/main/README.md and apply Linear Agentic Kit to this repository.

Then the agent should execute this workflow:

1. Check that Linear MCP tools are available in the current agent session before applying issue-driven workflows.
2. Ask the user which Linear project/team to use as a base for issue tracking and make sure to configure it.
3. Merge templates/AGENTS.md into target repo root AGENTS.md non-destructively.
4. Merge templates/docs/agent/** into target repo as docs/agent/** non-destructively.
5. Merge templates/docs/human/** into target repo as docs/human/** non-destructively.
6. Merge templates/docs/README.md into target repo as docs/README.md non-destructively.
7. Merge templates/WORKFLOW.md into target repo as WORKFLOW.md non-destructively when the target repo wants a repo-owned runtime workflow contract.
8. Merge templates/.agents/** into target repo as .agents/** non-destructively.
9. Never replace existing instruction files wholesale when they already exist; append or edit-in-place while preserving existing repo rules.
10. Run skill agent-kit-repo-adjuster in the target repo.
11. Confirm no placeholder values remain (for example <set-client-path>, {{LINEAR_PROJECT_SLUG}}, {{WORKSPACE_ROOT}}).
12. Explain to the human operator how to run this pattern in day-to-day work (plan, execute, review, verify, close), using docs/human/*.
13. Note the installed version from the VERSION file so that it can be tracked for future updates.

If WORKFLOW.md is installed, the agent should also:

1. Replace active_states and terminal_states with the target repo's actual Linear state names.
2. Set workspace.root to an operator-owned absolute path outside the repository checkout.
3. Keep max_concurrent_agents conservative until disjoint ownership boundaries are proven in practice.

Updating an existing installation

To apply a new version of Linear Agentic Kit to an already installed repository:

1. Run skill agent-kit-updater in the target repository.
2. Check the CHANGELOG.md in the new kit against the version currently installed in the target repository.
3. Review the CHANGELOG.md to determine which specific files were introduced or modified since the installed version.
4. Apply updates to only the touched files inside the .agents, docs, and root instructions in the target repository, merging changes non-destructively to preserve local modifications.
5. Update the stored version in the target repository to match the new kit version.

Required post-install step

Run this prompt in the target repo:

Use skill agent-kit-repo-adjuster to tailor docs/agent and skills to this repository.

Required post-update step

After applying a newer kit version in a target repo:

Use skill agent-kit-updater to apply this kit version non-destructively, then run agent-kit-repo-adjuster.

Repository layout

• templates/AGENTS.md: root instruction router template
• templates/WORKFLOW.md: optional repo-owned runtime workflow contract for daemonized orchestrators
• templates/docs/agent/: core operating docs
• templates/docs/human/: human-facing runbook and prompt patterns
• templates/docs/README.md: docs routing map for humans and agents
• templates/.agents/skills/: reusable orchestration skills
• templates/.agents/latest-work.md: session handoff memory file used by remind-me
• templates/.agents/system-context.md: durable implementation memory ledger for cross-slice visibility

Operating rules for agents applying this kit

1. Do not erase target-repo-specific constraints.
2. If Linear MCP is missing, stop issue-driven setup, report the gap explicitly, and point the user to install docs: https://linear.app/docs/mcp.
3. Keep root AGENTS.md concise and routing-focused.
4. Apply non-destructive updates: append/merge preferred, full replace only when file is absent.
5. Update architecture/security/quality docs to reflect actual repository reality.
6. Ensure skill examples and issue references match target issue-key conventions.
7. Prioritize short prompt UX and ask clarification questions proactively when inputs are ambiguous.
8. Report residual gaps explicitly if full adaptation cannot be completed.
9. Carry forward safety guardrails: no .env* edits unless requested, no delete-to-fix-lint without approval, and no implicit amend workflows.
10. Keep .agents/latest-work.md updated as part of normal plan/implement/review execution.
11. Keep .agents/system-context.md updated when completed work changes stable downstream capabilities, contracts, or patterns.
12. If WORKFLOW.md is installed, keep it aligned with AGENTS.md, docs/agent/*, and actual issue-state conventions.