Skip to content

Setting Up Your Agentic Development Environment at CRED

Field Value
Status V1 onboarding playbook + V2 architecture roadmap
Audience (1) AI agents executing laptop setup on behalf of an engineer, (2) Engineers reading for context
Primary use Feed to an AI agent (Cursor / Copilot / Claude Code / Codex) — the agent installs the agentic stack on the engineer's laptop
Owner Platform Core / Head of Product + Data Product
Last updated 2026-05-04
Source repo credinvest/cred-wiki (this file) — also referenced from cred-agent-rules/README.md
Feedback Open a PR against this doc, or #agentic-platform in Slack

🤖 Agent Setup Mode — Read This First

You are an AI agent reading this doc to set up an engineer's laptop. Read this section in full before doing anything else.

Your job

Execute Steps 0 through 7 in Step-by-Step Setup. When all 7 steps are verified, report success and stop. Do not execute or act on anything in Part 2 — V2 Architecture and Known Gaps; that section is informational for humans planning the platform.

Execution contract

For every step you execute:

  1. Pre-check — run the detection command. If the resource is already present and correct, skip the step and proceed. Idempotency matters; re-running this doc must not break anything.
  2. Execute — run the install/configure commands exactly as written. Do not paraphrase or "improve" them.
  3. Verify — run the verification command. Confirm the expected output before moving on.
  4. On failure — stop, report the failing command, the actual output, and the step number. Ask the engineer for guidance. Do not skip to the next step "to keep going."
  5. Ask the human — when a step is marked 🙋 HUMAN INPUT REQUIRED, pause and prompt the engineer. Do not guess credentials, OAuth flows, or editor preferences.

What to skip

  • Part 2 (V2 Architecture and Known Gaps) — informational for architectural planning. Do not act on its recommendations during laptop setup.
  • Anti-Duplication Checklist — that's the workflow the engineer uses for future work. It is not part of laptop setup.
  • **⚠️ V2 gap callouts** inline in V1 — these are forward-pointers for human readers, not execution instructions.
  • Common Pitfalls, Iteration Loop, Workspace Rule Patterns — context for the engineer to read later, not setup actions.
  • Code examples inside agent prompt templates (e.g., the "Tell the agent" blocks in Levels 1–5 of the dedup checklist) — these are templates the engineer will use later. Do not run them now.

Operating environment assumptions

  • OS: macOS (most CRED engineers) or Linux. Windows is not supported by this doc.
  • Shell: zsh or bash.
  • Network: access to GitHub, npmjs, Anthropic, Cursor, and Google Cloud is available.
  • Permissions: the engineer has admin rights on the laptop (can install apps, modify ~/.zshrc, etc.).

Definition of "done"

Setup is complete when all 7 steps' Verify checks pass and the engineer can:

  • Open a fresh chat in their chosen editor and ask "what are my user rules?" — agent summarizes the 9 rules
  • Run gh repo view credinvest/cred-plans — succeeds
  • Run make agent-rules in any seeded cred-* repo — reports "no changes"

Stop conditions

Stop and report to the engineer immediately if:

  • A pre-check shows an inconsistent state (e.g., partial install from a prior aborted run)
  • A verify command fails after a successful execute
  • The engineer's response to a 🙋 HUMAN INPUT REQUIRED is unclear
  • You encounter any auth/permission error you can't resolve from this doc
  • You're about to do something destructive (overwrite a file, delete a directory) that wasn't explicitly listed in this doc

How this doc is organized (for human readers)

This doc serves two purposes:

  1. V1 (Steps 0–7 below) — the workflow to adopt today. The agent reading this doc executes these steps to set up your laptop.
  2. V2 (Adversarial Review: V2 Architecture and Known Gaps) — informational only. A frank inventory of where V1 codifies anti-patterns and what the platform layer underneath it should look like. Not executed during setup.

Read both before assuming V1 is the end state. V1 is a process layer; V2 is the platform layer that should make most of V1 unnecessary.

Table of Contents

Part 1 — V1: Adopt the workflow today

Part 2 — V2: Where this is heading

Part 3 — Reference

A hands-on guide for engineers joining CRED to set up the same agentic workflow we use across the platform. Works with Cursor or VS Code (with GitHub Copilot agent mode and/or the Claude Code extension). The shared rule library (cred-agent-rules) renders to all three formats, so the underlying contract is the same regardless of editor.

⚠️ V2 gap: "Renders to all three formats" is rendering, not centralization. V2 mandates AGENTS.md as the only committed format and forces tool conformance instead of accommodating tool fragmentation. See §V2 Issue 1 below.

Follow this end-to-end and you'll have:

  • An IDE (Cursor or VS Code) wired into Linear, GitHub, BigQuery, ClickHouse, GCP, dbt, Figma, Vercel, and Supabase via MCP
  • The shared rule library (cred-agent-rules) installed and self-syncing in every repo you touch
  • Personal user rules tuned for honest, decisive AI-assisted work
  • The four-stage agentic development lifecycle running on every PR you open
  • 15 lifecycle agents reviewing your work automatically — pr_reviewer, test_builder, deploy_risk_assessor, etc.
  • Auto-publish of plans to cred-plans and protected AGENTS.md knowledge files

This doc is the source-of-truth setup playbook. If something's out of date, PR it.

Pick your editor

Editor Agent runtime What you get Best for
Cursor Native multi-model agents (Claude, GPT, Composer) Tightest agent UX, native MCP, Cursor Skills Engineers who want the most polished agent experience out of the box
VS Code + GitHub Copilot (agent mode) Copilot Chat with agent tools Reads .github/copilot-instructions.md (rendered by cred-agent-rules); MCP via Copilot agent Engineers already on VS Code who use Copilot
VS Code + Claude Code (extension or CLI) Anthropic's claude CLI / extension Reads CLAUDE.md and AGENTS.md (rendered by cred-agent-rules); MCP support; Claude Skills Engineers who prefer Claude and a more terminal-driven workflow

You can mix-and-match. Many engineers use Cursor for interactive work and Claude Code in the terminal for scripted/CI runs. Everything below works with whichever combination you pick.

TL;DR — The Stack at a Glance

The layers are the same across editors; only the paths differ. The columns marked Cursor / VS Code show where each artifact lives in each editor.

Layer What it is Cursor VS Code (Copilot / Claude Code)
IDE Editor with agent runtime Cursor app VS Code app + Copilot extension and/or Claude Code extension/CLI
Skills Reusable agent capabilities (babysit, canvas, split-to-prs, create-rule, …) ~/.cursor/skills-cursor/ Claude Code skills under ~/.claude/skills/ and ~/.claude/plugins/ (Copilot has no skills concept yet — uses prompt files instead)
MCP servers Tool integrations: Linear, GitHub, BigQuery, ClickHouse, GCP, Vercel, Figma, dbt, Supabase ~/.cursor/mcp.json Copilot: VS Code settings.json → github.copilot.chat.mcpServers. Claude Code: ~/.claude/mcp.json
User rules Personal behavioral defaults — calibration, permission-budget, role context Cursor → Settings → Rules → User Rules Copilot: settings.json → github.copilot.chat.codeGeneration.instructions. Claude Code: ~/.claude/CLAUDE.md
Workspace rules Repo-local rule files .cursor/rules/*.mdc Copilot: .github/copilot-instructions.md (rendered by cred-agent-rules). Claude Code: <repo>/CLAUDE.md (rendered by cred-agent-rules)
Shared rule library Central rules + routing + agents + hooks, distributed to every repo [credinvest/cred-agent-rules](https://github.com/credinvest/cred-agent-rules) — renders to all three formats automatically
Centralized plans All cross-repo plans, auto-published from agent chats [credinvest/cred-plans](https://github.com/credinvest/cred-plans) — editor-agnostic
Agent guides Repo-specific knowledge bases the agent reads as authoritative <repo>/AGENTS.md (read by all editors), plus <repo>/CLAUDE.md for Claude-specific overrides
Lifecycle agents 15 agents covering review, testing, deploy risk, design, architecture, learning Routed via cred-agent-rules/routing/rules.yml — runs on PRs server-side, editor-agnostic
Git hooks Distributed pre-push, post-merge, commit-msg .agent-rules/hooks/ (installed by cred-agent-rules) — editor-agnostic
CI GitHub Actions calling cred-agent-rules reusable workflows .github/workflows/agent-rules.yml — editor-agnostic

Key insight: the shared rule library, plans repo, lifecycle agents, hooks, and CI are all editor-agnostic — they run on the server (GitHub) or via committed git hooks. Only the four "client-side" layers (IDE, skills, MCP, user rules) differ between Cursor and VS Code, and cred-agent-rules auto-renders to both Cursor's and VS Code's formats.

The Agentic Development Lifecycle

Every non-trivial piece of work flows through this four-stage loop. Each stage has rules, agents, and CI gates that run automatically.

Stage 1: Discover  →  Check cred-plans for existing plans, then plan
Stage 2: Plan      →  Linear Epic + numbered, sized sub-issues
Stage 3: Execute   →  One sub-issue → one PR → agents review → merge → next
Stage 4: Capture   →  Update plan, log decisions, append to AGENTS.md

What runs at each stage

Stage Human / agent Tooling
Discover Search cred-plans, Linear, and the codebase for prior plans, tickets, and existing implementations Reference Centralized Plans Repo user rule; Check Existing Tickets Before Creating user rule; gh CLI; Linear MCP; codebase semantic search
Plan Draft in IDE → adversarial review by a second agent (fresh session, different model) → reconcile → create Linear Epic with phased sub-issues; write plan with frontmatter — only after passing the anti-duplication checklist Plan Mode → Linear Workflow user rule; plan-frontmatter.mdc workspace rule; auto-publish hook to cred-plans; see The Plan Mode Workflow below
Execute Implement sub-issue → PR → CI → agent review → merge → next cred-agent-rules PR routing → 15 lifecycle agents (pr_reviewer, test_builder, deploy_risk_assessor, design_feedback, etc.); GitHub Actions; pre-push hook enforcing rules
Capture Update plan status; log decisions; append discoveries Decision Logging user rule; protect-agents-md.mdc workspace rule; repo_learner / cross_repo_learner agents propose new rules

Hard constraints (V1 — enforced by rules + hooks + CI)

  • No duplicate work. Every Linear ticket, plan, Epic, sub-issue, and code change must pass the anti-duplication checklist below before it gets created.
  • One sub-issue = one PR. No mega-PRs.
  • Each PR ~200–400 LOC. Above ~500, review quality drops sharply. Split if needed (/split-to-prs skill).
  • Sequential execution. Don't start sub-issue N+1 until N is merged. Exception: provably independent work (different services, no shared files/schema).
  • No force-push (rule 0005). No secrets (rule 0006). Conventional commits (rule 0007). DB safety review for migrations (rule 0008). Tests required for code changes (rule 0010).
  • Auto-merge is opt-in per repo and currently global.enabled: false — humans still merge for now.

⚠️ V2 gaps in the constraints above:

  • "Sequential execution" is human-paced and contradicts the brief that work should run concurrently. V2 makes parallel the default via a depends_on DAG. See §V2 Issue 3.
  • "Each PR ~200–400 LOC" is a humans-reviewing-PRs heuristic. V2 lets each sub-issue declare pr_strategy: single | layered | split based on diff coupling. See §V2 Issue 10.
  • "Humans still merge" wastes the work the 15 lifecycle agents do. V2 introduces risk-tiered auto-merge. See §V2 Issue 5.

The Anti-Duplication Checklist (V1)

The biggest silent failure mode of AI-assisted work is doing work that's already been done. An agent will happily plan a feature someone else already shipped, write a utility that already exists three directories over, or open a Linear ticket that's a near-duplicate of one closed last sprint. This checklist is what the agent must run before creating any new artifact.

Run it at every level. The cost of the search is minutes; the cost of duplicate work is days plus the merge mess at the end.

⚠️ V2 gap: This checklist is a process burden that depends on a human or agent remembering to run it. Process is brittle; infrastructure is durable. V2 replaces each level with automation: Linear webhooks for L1/L2, an Epic-decomposer for L3, a schema/component registry for L4, federation for L5. See §V2 Issue 4. Until V2 ships, treat this checklist as the contract.

Level 1 — Plans (before drafting anything)

Search **cred-plans** for plans on the same topic across the platform:

# Search all plans across all repos
rg -i "<topic-keyword>" ~/Development/CRED/cred-plans/plans/

# Or via the agent: "search cred-plans for any plan touching <topic> across all repos"

Decision tree:

  • Match found, status in-progress or approved → don't write a new plan; update the existing one and link the Linear ticket
  • Match found, status draft or archived → review it first; surface to the original author before re-planning
  • Partial match (similar area, different scope) → link as related_plans: in your new plan's frontmatter, flag the overlap to the user
  • No match → proceed and contribute the plan back via the auto-publish hook

This is enforced by Rule 8 — Reference Centralized Plans Repo.

Level 2 — Linear tickets (before creating an Epic or any issue)

Before opening a new Linear Epic or issue, search Linear at three scopes:

  1. Your team's board — open + closed in the last 90 days, by title, description, and labels
  2. Adjacent teams' boards — Platform, Data, Product, Design (CRED work crosses team boundaries; the same problem often lives on multiple boards). Note Linear permissions: if a board is private, the search will silently miss matches there. Either request access to relevant adjacent boards or coordinate via Slack with that team's lead before proceeding.
  3. Existing Epics — could the new work be a sub-issue under an open Epic instead of a new Epic?
# Tell the agent:
"Before creating this Epic, search Linear across all CRED teams for open or
recently-closed issues matching <feature> / <service> / <keyword>. Return the
top 5 matches with status, owner, and last update. Then ask whether to create
new, link to existing, or fold into an existing Epic."

Decision tree:

  • Exact match exists → comment on it / reassign / reopen instead of creating new
  • Similar issue, different scope → create new but link as Related to and call out the overlap in the description
  • An open Epic already covers this area → create a sub-issue under that Epic instead of a new top-level Epic
  • No match → create the Epic, then enumerate existing sub-issues under it before adding new ones (next level)

This is enforced by Rule 5 — Check Existing Tickets Before Creating.

Level 3 — Sub-issues (before adding to an Epic)

Once you have an Epic (new or existing), enumerate its existing sub-issues before adding new ones:

# Tell the agent:
"List all sub-issues under Epic <EPIC-ID> with their status. For the proposed
sub-issues SUB-01..SUB-N, flag any that overlap with existing sub-issues, and
suggest renumbering or merging where there's overlap."

Decision tree:

  • Existing sub-issue covers this work → reuse it (reopen if closed, reassign if needed)
  • Existing sub-issue partially covers it → split: keep the covered part, add only the new delta as a new sub-issue
  • No overlap → add the new sub-issue with a sequential number that doesn't collide with existing numbering

Level 4 — Code (before implementing any sub-issue)

Before writing code for a sub-issue, search the target repo(s) for existing implementations of the same thing. Agents are particularly bad at this — they'll cheerfully reinvent a utility that already exists.

The two-pass search:

  1. Semantic search — describe the behavior you're about to implement and ask the agent to find similar existing code: 
     "Search this repo for existing utilities that <describe behavior>.
  Look for: helper functions, services, repositories, hooks, middleware.
  Return file paths and a one-line summary of each match."
  2. Symbol search — grep for likely names: 
     rg -i "(compute|calculate|fetch|build)<concept>" --type ts

Decision tree:

  • Existing implementation does what you need → import it. Don't reinvent.
  • Existing implementation does most of what you need → extend it (add a parameter, a variant) rather than fork it
  • Existing implementation is in the wrong place → consider moving it to a shared location before adding the new caller — flag the move as a separate sub-issue if it's >50 LOC of churn
  • No match → implement, but co-locate with similar functions and follow the repo's naming conventions

The **pr_reviewer** lifecycle agent flags suspected duplication in review (e.g., "this looks similar to src/utils/foo.ts — consider extending instead of reimplementing"). It's a backstop, not a substitute for doing the search up front.

Level 5 — Cross-repo (for platform work)

For work that spans repos (e.g., a new field that flows from cred-dbt → cred-model-api → cred-web-commercial):

  • Check cred-plans/plans/ across all affected repos, not just yours. The Relationship Graph Store work, for example, spans cred-api-commercial, cred-model-api, cred-dbt, and lives under the cred-api-commercial/ plans directory even though it touches all four.
  • Search for existing schemas, GraphQL types, or domain models with the same name in all affected repos.
  • Check cred-agent-rules/rules/ to see if a relevant cross-repo rule already governs this area.

One-line agent prompt for the full checklist

When opening a Plan Mode session, ask the agent up front:

"Before we plan this work, run the anti-duplication checklist:
1. Search cred-plans for matching plans across all repos
2. Search Linear (my team + adjacent teams) for open or recently-closed issues
3. List existing Epics that could absorb this work
4. Search the target repo(s) for existing code implementing the same behavior
5. Report findings with links and ask whether to proceed, fold, or extend"

If the agent skips this, call it back. The dedup check is the most expensive thing to skip.

The Plan Mode Workflow

This is the workflow engineers run for every assigned epic before opening Linear sub-issues and shipping code. It's the operational counterpart to the laptop setup above. Where setup gets you ready, this is what you do every time you plan a piece of work.

🤖 Agent note: This section describes a workflow the engineer will run. Do not execute it as part of laptop setup. Skip past it during the Step 0–7 install. Engineers running Plan Mode for a new feature should follow this section.

The 6-step Plan Mode loop

1. Pre-check     →   Run the Anti-Duplication Checklist (L1–L5 above)
2. Draft         →   Plan in your IDE with your primary agent (Cursor / Copilot / Claude Code)
3. Adversarial   →   Pass the draft to a SECOND agent (fresh session, different model) for review
4. Reconcile     →   Edit the plan based on the adversarial feedback; document decisions
5. Decompose     →   Create the Linear Epic with phased, numbered, sized sub-issues
6. Publish       →   Add YAML frontmatter; auto-publish hook syncs to cred-plans

Step 1 — Pre-check: anti-duplication

Run all 5 levels of the Anti-Duplication Checklist before drafting anything. If you skip it here, the rest of the workflow is wasted effort on potentially duplicate work.

Step 2 — Draft the plan in your IDE

In your primary agent (Cursor's Plan Mode, Copilot agent mode, or Claude Code interactive session), draft a plan covering:

  • Goal / outcome — what's true at the end that isn't true now
  • Scope — what's in, what's out
  • Phases — meaningful milestones, each independently shippable
  • Sub-issues — SUB-01, SUB-02, … under each phase, sized for ~200–400 LOC PRs
  • Dependencies — which sub-issues block which
  • Risks & open questions — surface what you don't know yet

Save the draft as plan-<feature>.md in your local working directory or cred-plans/plans/<repo>/. Don't add the auto-publish frontmatter yet — that's Step 6.

Step 3 — Adversarial review by a second agent

This is the load-bearing step. The primary agent that drafted the plan is biased toward its own approach — it will validate its own thinking. To catch the gaps, hand the draft to a different agent:

Adversarial reviewer setup When to use
Different model — if you drafted in Claude, review in GPT-5 or Codex (or vice-versa) Default. Different training distributions catch different blind spots.
Fresh session, same model — new chat, no prior context Faster. Use when context-switching to a different model is friction-heavy.
Different editor — drafted in Cursor, review in Claude Code or Copilot agent mode Useful for stress-testing tool-specific assumptions in the plan.

The prompt for the adversarial reviewer:

You are an adversarial reviewer. I have drafted a plan for <feature>. Your job is
NOT to validate it — your job is to find what's wrong, missing, or risky.

Review the attached plan against:

1. Anti-pattern check — does the plan codify any of: fragmented sources of truth,
   human-paced sequential execution where parallel is possible, manual processes
   where automation exists, duplicated code/logic that already exists in the
   codebase or platform-kit?

2. Decomposition check — are the sub-issues independently shippable? Sized
   right (~200–400 LOC)? Phased so the first 2 sub-issues deliver standalone
   value? Numbered without gaps?

3. Risk check — what fails first? What's the riskiest assumption? What happens
   if sub-issue N+1 reveals sub-issue N was wrong?

4. Dependency check — is the dependency DAG explicit? Could anything run in
   parallel that's currently sequenced?

5. Acceptance criteria check — for each sub-issue, are the acceptance criteria
   testable by an agent without human judgment?

6. Cross-repo / shared-code check — does this plan create new duplication?
   Is there an existing utility, schema, or component that should be extended
   instead?

7. Linear ticket check — search Linear (assume MCP access). Are there existing
   open or recently-closed tickets covering any sub-issue? Should this Epic fold
   into an existing one?

Return your findings ranked by severity:
- BLOCKER: must fix before creating the Linear Epic
- IMPORTANT: should fix; document the trade-off if you don't
- NICE-TO-HAVE: optional improvements

Do not soften the feedback. Be specific. Cite the section of the plan you're
critiquing.

Attach the plan draft. Wait for findings.

Step 4 — Reconcile

Read every BLOCKER and IMPORTANT finding. For each:

  • Accept — edit the plan to fix it
  • Reject with rationale — document why you disagree (this becomes a Decision Log entry)
  • Defer to Linear — create a follow-up sub-issue rather than blocking this Epic

If the adversarial review surfaces 3+ BLOCKERS, that's a signal the plan needs a more substantial rewrite — not patches. Go back to Step 2 with the feedback in hand.

Step 5 — Decompose into a Linear Epic

Only now create the Epic. Per User Rule 9 — Plan Mode → Linear Workflow:

  • One Epic for the overall work, with the plan summary as the Epic description and a link to the plan in cred-plans
  • Sub-issues numbered sequentially: SUB-01, SUB-02, … each independently shippable, ~200–400 LOC PR-sized
  • Phases as labels if the work has natural milestones (e.g., phase-1-foundation, phase-2-feature, phase-3-polish)
  • Dependencies declared in each sub-issue's description: "Depends on SUB-02. Blocks SUB-05."
  • Acceptance criteria on every sub-issue, testable without human judgment

If acceptance criteria aren't clear from the original card, stop and ask before fanning out sub-issues. (See the Slack note from leadership — ping the Epic owner same-day if criteria are ambiguous.)

Step 6 — Add frontmatter and publish

Add the plan-frontmatter YAML to the top of the plan file. The auto-publish hook syncs it to cred-plans/plans/<repo>/. Set linear_ticket to the Epic ID so the plan and Epic are bidirectionally linked.

---
title: "<feature> — <one-line outcome>"
repo: <exact-repo-name>
author: <your-name>
created: <YYYY-MM-DD>
status: approved              # bumped from draft after adversarial review passes
tags: [feature]
linear_ticket: "CRE-<id>"     # the Epic
related_plans: []
---

What "done" looks like for Plan Mode

You're ready to start executing sub-issue SUB-01 when:

  • ✅ Anti-Duplication Checklist clean (or overlaps documented)
  • ✅ Adversarial review BLOCKERS resolved
  • ✅ Linear Epic exists with numbered, sized, phased sub-issues
  • ✅ Dependencies declared on each sub-issue
  • ✅ Acceptance criteria testable without human judgment
  • ✅ Plan published to cred-plans with status: approved and linear_ticket set

Step-by-Step Setup

⚠️ V2 gap: The setup below is manual and adds friction — exactly what the brief said to avoid ("make our lives easier for development"). V2 collapses this into a single command: npx @cred/devkit init. See §V2 Issue 8. Until then, follow the steps.

Step 0 — System Prerequisites

Before any editor install, confirm these CLI tools and runtimes are present.

Pre-check (run all):

# Should all print a version. If any errors, install via Execute below.
git --version
gh --version
node --version    # require >= 20
python3 --version # require >= 3.10
gcloud --version  # required for BigQuery/GCP MCP
make --version
curl --version

Execute (only what's missing):

# macOS — install Homebrew first if needed:
which brew >/dev/null 2>&1 || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Then any missing tools:
brew install git gh node python@3.12 google-cloud-sdk make

Verify:

# Re-run the pre-check block above. All commands must print a version, no errors.

Authenticate gh and gcloud:

# 🙋 HUMAN INPUT REQUIRED — both commands open a browser for OAuth.
gh auth status || gh auth login                     # GitHub
gcloud auth application-default login                # GCP — needed for BigQuery MCP

Verify auth:

gh api user --jq '.login'              # should print the engineer's GitHub username
gcloud auth list --filter=status:ACTIVE --format='value(account)'  # should print their CRED email

On failure: any version mismatch or auth failure — stop and ask the engineer. Do not proceed.

Step 1 — Install editor(s)

🙋 HUMAN INPUT REQUIRED — ask the engineer: "Which editor(s) would you like to set up? Options: Cursor, VS Code + GitHub Copilot, VS Code + Claude Code, or any combination. Cursor is the recommended primary; you can add others later."

Then execute only the chosen options. Skip the others.

Option A — Cursor

Pre-check:

ls /Applications/Cursor.app 2>/dev/null && cursor --version 2>/dev/null

If both succeed, Cursor is installed — skip to Step 2.

Execute:

# macOS:
brew install --cask cursor
# After install, open Cursor once to register the `cursor` CLI:
open -a Cursor

🙋 HUMAN INPUT REQUIRED: "Sign in to Cursor with your CRED Google Workspace account, then install the cursor CLI from the command palette (Shell Command: Install 'cursor' command). Tell me when done."

Verify:

cursor --version    # must print a version
ls -d ~/.cursor      # must exist

Option B — VS Code + GitHub Copilot (agent mode)

Pre-check:

ls /Applications/Visual\ Studio\ Code.app 2>/dev/null && code --version 2>/dev/null
code --list-extensions 2>/dev/null | grep -E '^GitHub\.copilot(-chat)?$'

If VS Code is installed and both Copilot extensions are listed, skip the install steps.

Execute:

# Install VS Code if missing:
ls /Applications/Visual\ Studio\ Code.app 2>/dev/null || brew install --cask visual-studio-code

# Install Copilot extensions:
code --install-extension GitHub.copilot
code --install-extension GitHub.copilot-chat

🙋 HUMAN INPUT REQUIRED: "Open VS Code and sign in to GitHub when prompted. Confirm Copilot license is active (Platform Core manages org-level seats — ping #agentic-platform if licensing is unclear). Open the command palette and run Chat: Open Agent Mode — confirm it opens. Tell me when done."

Verify:

code --list-extensions | grep -E '^GitHub\.copilot(-chat)?$' | wc -l    # must print 2

Option C — VS Code + Claude Code

Pre-check:

which claude && claude --version
ls -d ~/.claude 2>/dev/null

If both succeed, skip the install steps.

Execute:

# Install the Claude Code CLI:
curl -fsSL https://claude.ai/install.sh | bash

# Source the new PATH:
exec $SHELL -l

🙋 HUMAN INPUT REQUIRED: "Run claude in your terminal and sign in with your Anthropic account when prompted (Platform Core manages org access). Tell me when done."

Verify:

claude --version    # must print a version
ls -d ~/.claude     # must exist

On failure (any option): report the exact error and stop. Do not proceed to Step 2.

Step 2 — Configure MCP servers

MCP (Model Context Protocol) is how agents reach external tools. The same servers work in all three editors; only the config file path differs.

Pre-check:

# Cursor:
test -f ~/.cursor/mcp.json && jq '.mcpServers // .servers | keys' ~/.cursor/mcp.json 2>/dev/null

# Claude Code:
test -f ~/.claude/mcp.json && jq '.mcpServers // .servers | keys' ~/.claude/mcp.json 2>/dev/null

If the file exists and lists at least linear, github, and bigquery (or their user- prefixed equivalents), MCP is partially configured. Cross-check against the server list below; add any missing.

Execute: write the MCP config file for each editor the engineer chose in Step 1.

The minimum server list (all editors use the same JSON shape):

Server Why you need it
user-linear Create/update Linear tickets (Epics + sub-issues) — used in every Plan Mode session
user-github PR creation, commenting, reading review threads — used by gh shell calls and direct agent operations
user-bigquery Query the warehouse for data product work and dbt model verification
plugin-clickhouse Query the commercial ClickHouse OLAP cluster
user-gcp-storage, user-gcp-observability, user-gcloud GCS objects, Cloud Logging/Monitoring, gcloud CLI
user-vercel Frontend preview deployment status
user-supabase Auth and dev databases
user-Figma Design handoff for cred-web-commercial work
user-dbt dbt Cloud job status, model lineage
cursor-app-control Lets agents create projects, move between worktrees
cursor-ide-browser Browser automation for frontend testing

Where to put the MCP config

Editor File
Cursor ~/.cursor/mcp.json
VS Code + Copilot settings.json → github.copilot.chat.mcpServers (or via the MCP UI in Copilot Chat)
VS Code + Claude Code ~/.claude/mcp.json (CLI) or via the Claude Code extension's MCP settings

Same JSON shape in all three — { "servers": { "<name>": { "command": "...", "args": [...] } } }. If Cursor was set up first, copy ~/.cursor/mcp.json to ~/.claude/mcp.json verbatim; for Copilot, paste the servers object into VS Code settings under github.copilot.chat.mcpServers.

🙋 HUMAN INPUT REQUIRED — ask the engineer: "For each MCP server, an OAuth flow may open in your browser. Approve each one (Linear, GitHub, etc.). For GCP/BigQuery, the gcloud auth from Step 0 is reused. Tell me when all OAuth approvals are done — or which servers you want to skip."

Verify:

In the engineer's chat in each chosen editor, run two test prompts and confirm real data comes back:

  1. Prompt: "List my open Linear issues assigned to me." — must return actual Linear issues
  2. Prompt: "Show me the last 5 PRs in credinvest/cred-dbt." — must return actual PR data via the GitHub MCP

If either prompt returns "no MCP server available" or generic LLM text instead of MCP tool calls, MCP is misconfigured.

On failure: report which server failed, paste the editor's error log location (~/.cursor/logs/ or VS Code Output → MCP). Stop.

Step 3 — Install Skills (or the editor's equivalent)

"Skills" are reusable agent capabilities — reusable prompts + scaffolding the agent can invoke by name. The mechanism differs per editor. Execute only the options matching the editor(s) chosen in Step 1.

⚠️ Verify the org's actual skills repo URLs with Platform Core before this step. The repo names below (credinvest/cred-cursor-skills, credinvest/cred-claude-skills) are conventional — confirm in #agentic-platform if the engineer doesn't already have access. If a repo doesn't exist yet, skip this step and report.

Option A — Cursor Skills

Pre-check:

test -d ~/.cursor/skills-cursor && ls ~/.cursor/skills-cursor/babysit 2>/dev/null

If the directory and the babysit skill exist, skip.

Execute:

mkdir -p ~/.cursor
gh repo clone credinvest/cred-cursor-skills ~/.cursor/skills-cursor 2>&1 | tail -3

Verify:

ls ~/.cursor/skills-cursor/{babysit,canvas,split-to-prs,create-rule}/SKILL.md
# All four must exist and be readable

Option B — Claude Code Skills

Pre-check:

test -d ~/.claude/skills && ls ~/.claude/skills/babysit 2>/dev/null

If both exist, skip.

Execute:

mkdir -p ~/.claude
gh repo clone credinvest/cred-claude-skills ~/.claude/skills 2>&1 | tail -3

Verify:

ls ~/.claude/skills/{babysit,split-to-prs,create-rule}/SKILL.md
# All three must exist and be readable

Option C — Copilot prompt files (no native skill concept)

Copilot agent mode doesn't have a "skills" feature today; it uses prompt files at .github/prompts/<name>.prompt.md. These get installed per-repo by cred-agent-rules in Step 5, so no action is needed in Step 3 for Copilot users.

On failure (Option A or B): if the skills repo clone fails with a 404, report to the engineer that the skills repo isn't published yet and ask whether to skip this step. Do not invent a fallback.

The skills you'll use most (across editors)

Skill When it fires
babysit Keeps a PR merge-ready: triages comments, resolves conflicts, fixes CI in a loop
canvas Renders quantitative analyses, billing investigations, MCP query results as live React canvases instead of markdown tables (Cursor only — VS Code uses notebooks instead)
split-to-prs Splits a fat branch into small reviewable PRs (use when a sub-issue grew beyond ~400 LOC)
create-rule Scaffolds a new rule file with proper frontmatter (.cursor/rules/*.mdc for Cursor, .github/copilot-instructions.md partial for Copilot)
create-skill Authors a new skill
create-hook Authors a new editor/git hook
statusline Configures the agent CLI status line
update-cursor-settings / update-vscode-settings Modifies your editor's settings file

The agent will offer skills automatically based on the conversation. You can also ask "use the babysit skill" by name.

Step 4 — Set your User Rules

The nine personal rules below are the team's recommended starting point. Install all nine, then the engineer can trim or adapt later. They apply to every chat across every repo.

Rule 7 (Role Context) is templated — it's currently written for a Tech Principal / Head of Product. The agent should ASK the engineer for their role before installing Rule 7 (see below).

Where to put your user rules (per editor)

Editor Where
Cursor Settings → Rules → User Rules (single text box; paste all rules below)
VS Code + Copilot settings.json → github.copilot.chat.codeGeneration.instructions (array of { "text": "..." } objects, one per rule)
VS Code + Claude Code ~/.claude/CLAUDE.md (single markdown file; paste all rules with ## Rule N headings)

Pre-check

# Cursor — must be inspected via the GUI; ASK the engineer:
# "Open Cursor → Settings → Rules → User Rules. Are the 9 rules already there?
#  If yes, skip Step 4. If no or partial, proceed."

# Claude Code:
test -f ~/.claude/CLAUDE.md && grep -c "^## Rule [1-9]" ~/.claude/CLAUDE.md   # should print 9 if installed

Execute

🙋 HUMAN INPUT REQUIRED — ask the engineer: "What's your role? E.g., 'Senior Backend Engineer', 'Data Engineer', 'Frontend Engineer', 'Tech Principal', etc. This will be used to customize Rule 7 (Role Context). Also tell me how much pushback you want from the agent: high, medium, or low."

After the engineer answers, fill in Rule 7 below using the answer. Then install all 9 rules into the destination(s) for the editor(s) chosen in Step 1.

For Cursor: ASK the engineer to open Settings → Rules → User Rules and paste the rules in. The agent cannot edit Cursor user rules programmatically.

For VS Code + Copilot: write to settings.json. Use the JSON shape:

{
  "github.copilot.chat.codeGeneration.instructions": [
    { "text": "<Rule 1 content>" },
    { "text": "<Rule 2 content>" },
    // ... one entry per rule
  ]
}

For VS Code + Claude Code: write ~/.claude/CLAUDE.md with the full content below, using ## Rule N — <name> headings.

Verify

# Claude Code:
grep -c "^## Rule [1-9]" ~/.claude/CLAUDE.md           # must be 9

# Copilot:
jq '.["github.copilot.chat.codeGeneration.instructions"] | length' ~/Library/Application\ Support/Code/User/settings.json   # must be >= 9

For Cursor, ASK the engineer to confirm: "Open a fresh chat and ask 'what are my user rules?' — does the agent summarize 9 rules including 'Honest Status' and 'Stop Asking, Start Doing'?"

The 9 rules (verbatim — install all)

The content below is editor-agnostic — only the destination differs.

Rule 1 — Honest Status

When reporting progress:
- "Done" means tested and verified, not "code written"
- Surface blockers and unknowns immediately, not at the end
- If you're guessing, say so

Rule 2 — Stop Asking, Start Doing

Don't ask permission for obvious next steps. If I say "fix the bug,"
don't ask "should I write a test?" Just do it and tell me what you did.
Ask only when the choice materially changes the outcome.

Rule 3 — Data Product Rigor

For data product work:
- Always specify data source, freshness, and ownership
- Flag PII/sensitive data handling explicitly
- Question metric definitions before building (e.g., "active user" by what definition?)
- Prefer reproducible queries over one-off scripts

Rule 4 — Decision Logging

For any non-trivial technical or product decision:
- Capture the decision, alternatives considered, and rationale
- Suggest logging it in the relevant Linear ticket, ADR, or doc
- Don't let decisions live only in chat

Rule 5 — Check Existing Tickets Before Creating

Before creating any Linear ticket:
1. Search Linear for existing tickets matching the topic (title, description, labels)
2. If a match exists: link to it and ask if I want to update, comment, or create new
3. If similar but not exact: surface the matches and confirm before creating
4. Only create new if no overlap found

Never create duplicates silently.

Rule 6 — AI-First Approach

Default to AI-first solutions in all recommendations:
- When designing features, evaluate if AI/LLM/ML can replace or augment traditional logic
- For workflows, propose agent-based automation before manual processes
- For data products, consider embeddings, semantic search, and LLM extraction over rule-based parsing
- Flag when a non-AI approach is genuinely better (don't force AI where it doesn't fit)

Rule 7 — Role Context (adapt to your role)

I'm a Technical Principal and Head of Product + Data Product.

Default to:
- Strategic over tactical framing
- Trade-offs and second-order effects, not just solutions
- Push back when my reasoning is weak; don't agree to agree

Adapt the seniority, focus area, and how much pushback you want. Examples:

  • "I'm a Senior Backend Engineer. Default to: tactical framing, concrete code over abstractions, push back when my approach has hidden complexity."
  • "I'm a Data Engineer. Default to: schema and pipeline implications first, performance trade-offs, push back on unbounded queries."

Rule 8 — Reference Centralized Plans Repo

Before executing any plan, check github.com/credinvest/cred-plans for relevant
existing plans across the CRED platform.

- Search the repo for plans matching the current task (by feature, service, or keyword)
- If a relevant plan exists: follow it as the source of truth. Flag any deviations needed.
- If no plan exists: proceed with your own plan, then consider if it should be contributed back.
- If plans conflict with the user's request: surface the conflict before executing,
  don't silently override.

Rule 9 — Plan Mode → Linear Workflow

When plan mode is invoked:

Create Linear Epic with sub-issues numbered sequentially (SUB-01, SUB-02...).
Each sub-issue must be independently shippable.

Execute sub-issues in order. For each:
- Implement the change
- Open a PR (medium-sized, ~200-400 LOC; split if larger)
- Run tests, verify CI passes
- Resolve all critical/blocking PR comments before merge
- Update Linear status: In Progress → Delivered → Deployed

Constraints:
- One sub-issue = one PR (prefer multiple medium PRs over one large)
- Do not start sub-issue N+1 until N is merged
- If blocked, update Linear with blocker and stop

Verify: start a fresh chat in your editor (Cursor / Copilot agent / Claude Code) in any repo and ask "what are my user rules?" The agent should summarize the nine rules above. If it can't, the rules aren't loaded — re-check the file/setting path for your editor.

Step 5 — Install cred-agent-rules in each repo you work in

cred-agent-rules is the source of truth for cross-repo behavioral rules, PR routing, auto-merge policy, and the lifecycle agent catalog. Once installed in a repo, rule updates propagate passively on every git pull.

🙋 HUMAN INPUT REQUIRED — ask the engineer: "Which cred- repos do you currently have cloned locally? List the absolute paths. I'll run the installer in each. If you don't have any cloned yet, I'll skip this step and you can run it later when you clone your first repo."*

Per-repo Pre-check

For each repo path the engineer provided:

test -d "<repo-path>/.agent-rules" && cat "<repo-path>/.agent-rules/MANIFEST.json" 2>/dev/null

If .agent-rules/ exists and MANIFEST.json parses, the seed PR has already been merged in that repo — skip.

Execute (per repo)

cd <repo-path>
curl -fsSL https://raw.githubusercontent.com/credinvest/cred-agent-rules/main/scripts/install-into-repo.sh | bash

The installer:

  1. Fetches the latest cred-agent-rules dist/ (rules.json, routing-compiled.json, agents-catalog.json, global.md)
  2. Places .agent-rules/ (committed rule files, hook bodies)
  3. Adds .github/workflows/agent-rules.yml — thin wrapper invoking cred-agent-rules's reusable sync.yml
  4. Adds Makefile target agent-rules for local refresh
  5. Renders tool-specific files for all editors simultaneously:
  6. .cursor/rules/cred-agent-rules.mdc (Cursor)
  7. .github/copilot-instructions.md (VS Code + Copilot)
  8. .claude/CLAUDE.md (Claude Code)
  9. Marker-block upsert in root AGENTS.md (read by all editors)
  10. Activates git hooks: chains into existing husky/lefthook, or sets core.hooksPath directly
  11. Runs smoke tests
  12. Leaves a staged diff for you to review, commit, PR, merge

After the seed PR merges, you don't think about it again — the post-merge hook self-syncs the repo to cred-agent-rules's main on every git pull. Whichever editor you switch to (or use side-by-side), the latest rules are already rendered for it.

⚠️ V2 gap: Self-syncing to main is unbounded blast radius. A bad merge to cred-agent-rules ships to every developer in every repo on their next pull, with no canary or kill switch. V2 pins consumer repos to versioned releases (cred-agent-rules@v1.4.2), rolls new versions out via canary cohort (1 → 3 → org-wide), supports a single-flag kill switch, and instruments rule-firing telemetry. See §V2 Issue 6.

🙋 HUMAN INPUT REQUIRED: After the installer runs, the engineer must review the staged diff, commit, push to a branch, open the seed PR, and merge. The agent should NOT auto-commit or auto-merge this — Rule 0011 explicitly blocks auto-merge for cred-agent-rules consumer changes.

Verify (per repo, after the seed PR is merged)

cd <repo-path>
make agent-rules         # must report "no changes"
test -f .agent-rules/MANIFEST.json && jq -r '.version' .agent-rules/MANIFEST.json    # must print a version like "1.4.2"
ls .agent-rules/hooks/{pre-push,post-merge,commit-msg}    # all three must exist

On failure: if make agent-rules shows pending changes after a merge, the post-merge hook didn't fire. Run the installer again manually. If hook files are missing, core.hooksPath may not have been set — report and stop.

Step 6 — Connect to cred-plans

cred-plans is the centralized plans repo and the first stop in the anti-duplication checklist (Level 1). The plan-frontmatter.mdc workspace rule auto-publishes any plan the engineer creates.

Pre-check

test -d ~/Development/CRED/cred-plans/.git && (cd ~/Development/CRED/cred-plans && git remote get-url origin)
# Expected output: https://github.com/credinvest/cred-plans.git or git@github.com:credinvest/cred-plans.git

If the directory exists and points to the right remote, skip.

Execute

mkdir -p ~/Development/CRED
gh repo clone credinvest/cred-plans ~/Development/CRED/cred-plans

Verify

ls ~/Development/CRED/cred-plans/plans/    # must list per-repo subdirectories
test -f ~/Development/CRED/cred-plans/AGENTS.md && head -5 ~/Development/CRED/cred-plans/AGENTS.md

Reminder for the engineer (not a setup action)

Operational habit (for future use): Before any Plan Mode session, the engineer should ask their agent: "Search cred-plans across all repos for existing plans on <topic> and report back with status, owner, and a one-line summary of each match." User Rule #8 (already installed in Step 4) enforces this.

On failure: if the clone fails with a 404, the engineer doesn't yet have access to credinvest/cred-plans. Stop and ask the engineer to request access in #agentic-platform.

Plan frontmatter shape:

---
title: "Descriptive Plan Title"
repo: cred-dbt              # exact repo name; never inferred
author: <your-name>
created: 2026-05-04
status: draft               # draft | approved | in-progress | completed | archived
tags: [feature]             # at least one of: feature | migration | refactor | bug-fix | infrastructure | investigation
linear_ticket: ""           # CRE-1234 if applicable
related_plans: []
---

Plans without valid frontmatter are silently dropped by the auto-publish hook — the rule explicitly states this so the agent treats it as load-bearing.

Step 7 — Verify your hooks are wired

After Step 5, three hooks should be active in every seeded repo:

Hook What it does Failure mode
pre-push Runs the rule corpus (rules/0001–0010) against staged changes — blocks push on violations Push aborted with the failing rule's enforcement block
post-merge Pulls latest cred-agent-rules and re-runs the installer Silent unless drift exists; logs to .agent-rules/last-sync.log
commit-msg Enforces conventional commits (feat:, fix:, docs:, etc.) per rule 0007 Commit rejected, prints the expected format

Pre-check (per seeded repo)

cd <repo-path>
ls .agent-rules/hooks/{pre-push,post-merge,commit-msg}
git config core.hooksPath || ls .husky 2>/dev/null || ls .lefthook* 2>/dev/null
# At least one must exist — confirms a hook manager is wired

Verify (executed in a sandbox branch — these tests intentionally fail commands)

cd <repo-path>
git checkout -b setup-hook-verify-$(date +%s)

# Test 1 — pre-push secrets check (rule 0006). This MUST fail.
echo 'AWS_SECRET_ACCESS_KEY="AKIAIOSFODNN7EXAMPLE"' > /tmp/leak.env
cp /tmp/leak.env ./leak-test.env
git add leak-test.env
if git commit -m "feat: test secrets check"; then
  echo "FAIL: rule 0006 did not block the secret"; exit 1
else
  echo "PASS: rule 0006 blocked the commit as expected"
fi
git reset HEAD leak-test.env && rm -f leak-test.env

# Test 2 — commit-msg conventional-commits check (rule 0007). This MUST fail.
if git commit --allow-empty -m "stuff"; then
  echo "FAIL: rule 0007 did not block the non-conventional message"; exit 1
else
  echo "PASS: rule 0007 blocked the commit as expected"
fi

# Cleanup the verification branch
git checkout -
git branch -D setup-hook-verify-*

Expected output: both PASS lines printed.

On failure: if either test does NOT print PASS, hooks aren't wired. Run bash .agent-rules/scripts/install-hooks.sh if the script exists, or re-run the Step 5 installer. If still failing, stop and ask the engineer.

✅ Setup Complete — Stop Here

Agent: if all 7 steps' Verify checks passed, setup is done. Report success to the engineer with the summary below and stop.

Agentic environment setup complete. Verified:
- Step 0: System prerequisites (gh, git, node, gcloud auth)
- Step 1: Editor(s) installed and signed in: <list>
- Step 2: MCP servers configured and authenticated: <list>
- Step 3: Skills installed: <list, or "skipped — Copilot only">
- Step 4: 9 user rules installed in <editor(s)>
- Step 5: cred-agent-rules seeded in <N> repo(s): <paths>
- Step 6: cred-plans cloned to ~/Development/CRED/cred-plans
- Step 7: Hooks verified (pre-push secrets check + commit-msg conventional-commits both blocked as expected)

Next: open a Cursor / Copilot / Claude Code chat in any seeded repo and run a test prompt:
  "List my open Linear issues, then summarize the top 3 plans in cred-plans for cred-dbt."

Do NOT proceed to read or execute Part 2 below. Part 2 is the V2 architectural review — informational only, for human readers planning the platform. Setup ends here.

What cred-agent-rules Gives You

Once installed, your repo benefits from a centralized control plane. Here's what's in it.

The shared rule corpus (rules/)

12 versioned rules, each with frontmatter declaring enforcement (pre-push hook, agent-only, or advisory) and applicable_repos:

ID Rule What it prevents
0001 no-push-after-merge Pushing to a branch already merged
0002 never-merge-prs Agents auto-merging without policy approval
0003 default-base-develop PRs against the wrong base branch
0004 github-mcp-identity-guard Agent acting under wrong GitHub identity
0005 no-force-push History rewrites that break review state
0006 no-secrets Committing API keys, tokens, credentials
0007 conventional-commits Non-standard commit messages
0008 db-safety Unsafe migrations (no rollback, missing index, etc.)
0009 squash-on-merge Merge-commit pollution on main
0010 tests-required Code changes without tests
0011 no-auto-merge-for-planning-rule-repos Auto-merge gate on cred-plans and cred-agent-rules
0015 auto-open-pr-no-confirmation Agent pausing between commit, push, and PR open — agent should ship the whole sequence by default unless an explicit exception applies (plan-only, cred-plans/cred-agent-rules changes, irreversible ops, failed verification)

Authoring new rules: PR against rules/. CI runs build/validate.py (frontmatter + JSON Schema validation + reproducible build). CODEOWNERS requires 2 approvals.

The 15 lifecycle agents (agents/)

⚠️ V2 gap: This is a catalog, not a system. There's no shared findings format, cost/latency budget, conflict-resolution protocol when agents disagree, telemetry on precision/recall, prompt versioning, or back-pressure on repo_learner flooding the queue with rule-proposal PRs. V2 defines an AgentRun protocol: structured findings, severity, confidence, citation; orchestrate_review dedupes and renders one comment, not 15; per-agent telemetry to PostHog/BigQuery. See §V2 Issue 7.

Agent Phase What it does
pr_reviewer Prevention Reviews diffs for correctness, security, performance — posts machine-readable findings
test_builder Prevention Generates missing tests for code changes
product_analyst Prevention Validates product requirements against the diff
design_feedback Prevention Reviews UI changes against design system tokens (only fires on *.tsx/*.scss)
architecture_planner Prevention Reviews large PRs (>1000 LOC) and arch-review-labeled PRs
deploy_risk_assessor Prevention Flags risky migrations, schema changes, data ingestion edits
regression_fixer Prevention Auto-fixes regressions surfaced by other agents
requirements_generator Prevention Drafts requirements docs from PR context
documentation_generator Prevention Updates docs/AGENTS.md based on the diff
post_deploy_monitor Detection Watches metrics post-deploy, opens incidents if anomalies
orchestrate_review Orchestration Runs the full review fan-out for a PR
pr_router Orchestration Decides which agents run on a PR (consumes routing-compiled.json)
pr_merger Orchestration Auto-merges eligible PRs (currently disabled globally)
repo_learner Learning Proposes new rules based on patterns in this repo
cross_repo_learner Learning Promotes rules that have proven useful across multiple repos

PR routing (routing/rules.yml)

Per-repo defaults plus path-based, label-based, author-based, and size-based overrides. Examples:

  • cred-web-commercial: base [pr_reviewer, test_builder, product_analyst], plus design_feedback if any *.tsx/*.scss changed, minus everything if only docs/ changed
  • cred-api-commercial: deploy_risk_assessor automatically added when migrations or DB repository code changes (rule 0008)
  • Any repo, PR > 1000 LOC: architecture_planner added automatically
  • Label security-sensitive: forces pr_reviewer with the security profile
  • Label arch-review: adds architecture_planner
  • Label hold: clears all agents until removed

Auto-merge (routing/auto-merge.yml)

Currently global.enabled: false. Per-repo gates exist for when we turn it on. Until then, humans merge.

⚠️ V2 gap: "Humans always merge" is the most expensive policy you could pick. If the 15 lifecycle agents do real work, then human re-review of a green agent-passed PR is wasted dev effort. V2 risk-tiers the policy: Tier 0 (auto-merge on green) for docs-only and generated code; Tier 1 (auto-merge after 2 agent approvals + 1h soak) for non-DB feature work; Tier 2 (human required) for migrations, security-sensitive paths, arch-review label, and changes to cred-agent-rules/rules/0001–0010. See §V2 Issue 5.

Continuous learning (learning/)

repo_learner and cross_repo_learner watch for repeated PR-comment patterns and propose new rules via PR. learning/promotion-policy.md defines the thresholds for promoting a per-repo rule to a cross-repo rule. learning/runbook.md documents what to do when a learner opens a PR you disagree with.

Workspace Rule Patterns

Beyond the shared cred-agent-rules corpus, individual repos commit their own rule files for repo-specific behaviors. The file format depends on the editor: Cursor reads .cursor/rules/*.mdc (with frontmatter triggers), Copilot reads .github/copilot-instructions.md (single file with sections), Claude Code reads <repo>/CLAUDE.md. The patterns below describe what to encode — the renderer in cred-agent-rules produces all three formats from a single source of truth.

Three patterns we use repeatedly:

Pattern A — Structured metadata enables automation

plan-frontmatter (Cursor .mdc with alwaysApply: true; equivalent section in copilot-instructions.md / CLAUDE.md) forces every plan to include the YAML frontmatter required by the auto-publish hook. The rule explicitly states "plans without valid frontmatter are silently dropped" — naming the failure mode makes the agent treat it as load-bearing, not cosmetic.

Pattern B — Asymmetric protection for high-leverage artifacts

⚠️ V2 gap: A behavioral rule that says "don't delete things" is a workaround for missing primitives: strong typing on the protected content (machine-checkable so deletions break a build, not a rule), append-only storage with audit, and a retention policy. "Learned Workspace Facts" is unboundedly append-only — it'll be 10k lines in a year, which the agent can't reason over efficiently. V2 converts learned-facts into structured YAML/JSON entries (one fact per file, or rows in a table) the agent queries by topic. The protection rule becomes a CODEOWNERS rule on the directory, not a behavioral instruction. See §V2 Issue 15.

protect-agents-md (Cursor .mdc with globs: AGENTS.md; conditional section in copilot-instructions.md / CLAUDE.md) makes additions cheap and deletions expensive:

  1. Never remove sections, rows, or paragraphs unless explicitly asked by name. "Clean up" / "simplify" do NOT mean remove.
  2. Before saving any edit, compare planned output line count vs current. If reducing by >5 lines, stop and confirm.
  3. Adding content is always safe.
  4. Moving content must preserve all text. Verify line count >= original after restructure.
  5. When editing a section, read only that section. Never rewrite the whole file.
  6. "Learned Workspace Facts" are especially protected — never remove, summarize, or condense.

Apply to anything where accidental loss is expensive: schema files, migration scripts, RBAC configs, prompt libraries.

Pattern C — Cross-repo references for shared standards

The same idempotency pattern as ticket-search, applied to architectural plans across repos. Implemented via Rule 8 (user rule) + auto-publish hook (workspace) + cred-plans repo (canonical store). Closed loop.

Frontmatter triggers (Cursor .mdc files)

Cursor .mdc rules use frontmatter to control firing. Pick the narrowest trigger that works:

Frontmatter Fires when Use for
alwaysApply: true Every prompt in the repo Repo-wide invariants
globs: ["AGENTS.md"] Matching files touched File-specific behaviors
description: "..." Agent decides task matches Specialized opt-in workflows

alwaysApply: true is a token tax on every prompt — use sparingly.

AGENTS.md, CLAUDE.md, and copilot-instructions.md

Rule files (.cursor/rules/, copilot-instructions.md, CLAUDE.md) tell the agent how to behave. AGENTS.md tells it what's true about this codebase.

AGENTS.md is the editor-agnostic knowledge base — it's read by Cursor, Copilot, and Claude Code alike. The two tool-specific files (CLAUDE.md, .github/copilot-instructions.md) hold any quirks that only apply to that tool. Most of the time, you only need AGENTS.md.

Patterns that pay off:

  • Lead with the system map. First section: what does this repo do, what's the stack, what's the branching strategy. The cred-dbt/AGENTS.md example does this in a single table at the top — copy that shape.
  • Document the gotchas, not the obvious. If the framework docs cover it, don't repeat it. Document what surprised you.
  • Have a "Learned Workspace Facts" section. Hard-won discoveries from real debugging sessions. Treated as append-only; protected by protect-agents-md (rendered into .cursor/rules/protect-agents-md.mdc by cred-agent-rules).
  • Keep tool-specific files thin. Put shared truth in AGENTS.md. Use CLAUDE.md and copilot-instructions.md only for the small set of behaviors that genuinely differ per tool. The cred-agent-rules installer manages all three from a single source.

When to Write Your Own Rule (and When Not To)

Write a rule when:

  • You've corrected the same agent behavior more than twice
  • The desired behavior depends on context the agent doesn't have access to
  • A failure mode is silent or expensive
  • The rule unlocks downstream automation

Don't write a rule when:

  • It's a one-off preference for a single task — just say it in the prompt
  • The agent already does the right thing by default
  • The rule is too vague to act on ("be careful", "write good code")
  • It contradicts another rule without resolution

How to author it:

Scope Cursor VS Code + Copilot VS Code + Claude Code
Personal Settings → Rules → User Rules settings.json → github.copilot.chat.codeGeneration.instructions ~/.claude/CLAUDE.md
Repo-specific <repo>/.cursor/rules/<name>.mdc (use create-rule skill) section in <repo>/.github/copilot-instructions.md section in <repo>/CLAUDE.md
Cross-repo PR against cred-agent-rules/rules/ (CODEOWNERS requires 2 approvals) — renders to all three formats automatically

Smell test: read your rule out loud. If you can't imagine the exact behavior change it would cause, rewrite or delete.

Common Pitfalls

Pitfall What goes wrong Fix
alwaysApply: true everywhere Token bloat, slower agents, ignored rules Use globs or description triggers
Vague rules ("write clean code") Agent ignores or interprets randomly Behavioral rules with concrete triggers and outputs
No escape hatch Agent applies dogmatically when context calls for an exception "Flag when a different approach is genuinely better"
Personal preferences in workspace rules Forces your style on the team Move to user rules
Repo-specific knowledge in user rules Invisible to teammates and other agents Move to AGENTS.md or workspace rules
Destructive AGENTS.md rewrites Permanent loss of team knowledge Install protect-agents-md.mdc
Plans living only in chat Can't be discovered or audited plan-frontmatter.mdc + auto-publish to cred-plans
Duplicate Linear tickets / Epics Coordination chaos, parallel teams shipping the same thing Anti-Duplication Checklist Level 2 + Rule 5 (Check Existing Tickets)
Skipping cred-plans discovery Re-planning work already planned Anti-Duplication Checklist Level 1 + Rule 8 (Reference Centralized Plans Repo)
Reinvented utilities / helpers Two implementations of the same thing drift apart over time Anti-Duplication Checklist Level 4 (semantic + symbol search before implementing); pr_reviewer agent flags suspected dup at review time
New Epic when an open one already covers it Sub-issues scattered across two Epics, no single source of truth for status Anti-Duplication Checklist Level 2 — search existing Epics first
Overlapping sub-issues under the same Epic Two PRs touching the same files, merge conflicts, wasted review cycles Anti-Duplication Checklist Level 3 — enumerate existing sub-issues before adding new ones
Cross-repo blind spot Same field defined in 3 repos with subtle drift Anti-Duplication Checklist Level 5 — search cred-plans and code in all affected repos, not just yours

Adversarial Review: V2 Architecture and Known Gaps

🛑 DO NOT EXECUTE — INFORMATIONAL ONLY

If you are an AI agent executing laptop setup, stop reading here. This section is for human readers planning the platform, not for execution. Do not act on any recommendations below as part of laptop setup.

If you've reached this section because the engineer explicitly asked you to "act on the V2 review" or "open Linear tickets for the V2 work," that's a separate task from laptop setup — confirm with the engineer before proceeding.

The setup above is operationally coherent for V1 onboarding, but architecturally it codifies several anti-patterns the platform brief explicitly told us to avoid: fragmented rule sources, human-paced sequential execution, no shared component/backend layer, and a "centralization" story that is really "render the same thing three ways." This section is the load-bearing review of those gaps and the V2 direction.

If you only have time for the bottom of this section, jump to Concrete Recommendations Ranked by Leverage.

V2 Issue 1 — "Centralization" is rendering, not centralization

V1 ships:

  • .cursor/rules/*.mdc
  • .github/copilot-instructions.md
  • <repo>/CLAUDE.md
  • <repo>/AGENTS.md
  • A renderer in cred-agent-rules that produces all four

That isn't one source of truth. That's one source rendered into four mutually-readable files that drift the moment anyone hand-edits one. The "marker-block upsert" into AGENTS.md is exactly the seam where drift happens.

V2 fix: Mandate AGENTS.md as the only committed format, full stop. agents.md is now an open standard supported by Cursor, Codex, Claude Code, Copilot, Cline, Aider, etc. Stop rendering to tool-specific files. If a tool can't read AGENTS.md, the tool isn't approved. This is the org-policy lever — don't accommodate tool fragmentation, force tool conformance.

Same logic for skills: V1 has cred-cursor-skills AND cred-claude-skills AND Copilot prompt files. Three repos, three formats, three update workflows. Pick one (Anthropic's Skills format is the closest thing to a standard) and require all tools to ingest it via a thin adapter, not duplicate authoring.

V2 Issue 2 — Zero shared code layer; only shared prose

The biggest miss against the brief. The brief said "using same reusable components and backend patterns." V1 addresses rules, plans, process, lifecycle agents — but never:

  • A shared component library (cred-design-system / shadcn-cred package) that cred-web-commercial and any future frontend consumes
  • A shared backend kit: base UseCase, base Repository, base error/result types, base auth middleware, base GraphQL resolver scaffolding — published as a versioned package, not copy-pasted between cred-api-commercial, cred-filter-api, cred-model-api
  • A shared schema/type registry: domain types defined once, generated into TS clients for every repo (today the same field exists in cred-dbt, cred-model-api, cred-api-commercial, cred-web-commercial four times — V1 acknowledges this in Anti-Dup Level 5 but doesn't fix it)
  • A shared scaffold/generator layer (Nx-style or Plop-style) so an agent doesn't implement a new use case, it generates one with all conventions baked in

The Anti-Duplication Checklist Level 4 is a manual rg and semantic search per task. That's compensating for missing infrastructure. You can't search-your-way out of architectural duplication. The right answer is a registry the agent queries, not a search the agent performs.

V2 fix: Add a parallel workstream — cred-platform-kit — that publishes:

  1. @cred/ui (shadcn-cred + tokens)
  2. @cred/backend-kit (UseCase / Repository / errors / auth / logging)
  3. @cred/schema (domain types, generated from a single source — likely the GraphQL supergraph or dbt models)
  4. @cred/generators (CLI: npx cred new use-case, npx cred new resolver, npx cred new react-page)

Now "one PR changes behavior for all repos" applies to code, not just rules.

V2 Issue 3 — Sequential sub-issue execution contradicts the brief

The brief said "don't assume dev work takes human time, planning must assume work runs concurrently by agents." Then User Rule #9 says:

Do not start sub-issue N+1 until N is merged.

That is human-paced. With agentic execution and a proper dependency DAG, sub-issues should:

  • Declare their dependencies explicitly in frontmatter (depends_on: [SUB-01])
  • Fan out in parallel where the DAG permits
  • Be dispatched to Cursor Cloud Agents / Claude SDK runners / Codex tasks concurrently
  • Reconverge with automated rebase/merge

V1's "exception: provably independent work" is the normal case under the brief, not the exception. Invert the default.

V2 fix: Sub-issue frontmatter must include depends_on: [] and parallelizable: true|false. A dispatcher (cron'd GitHub Actions job or an MCP tool) reads the Epic, computes the DAG, and spawns N parallel cloud agents. Sequential is the fallback, not the default.

V2 Issue 4 — Anti-Duplication Checklist is process burden, not infrastructure

Every level of the V1 checklist depends on a human or agent remembering to run it. The brief said "automate everything." The V2 shape:

  • L1 (plans): Linear webhook → on Epic creation, automation searches cred-plans + open Epics, posts a comment listing matches, blocks status transition until a human acks "no, this is new" or "yes, fold into X"
  • L2 (tickets): Pre-create hook (Linear API + LLM dedup classifier) before the ticket exists
  • L3 (sub-issues): Auto-generated from the Epic plan via an epic-decomposer job that consumes plan frontmatter; humans don't number sub-issues at all
  • L4 (code): @cred/generators + a component/symbol registry (auto-generated from tsdoc + @cred/schema) replace the manual rg. Agent queries the registry first; PR check fails if the diff exports a symbol whose semantic embedding is >0.9 similar to an existing one
  • L5 (cross-repo): GraphQL supergraph + schema registry are the dedup source. Adding a field that already exists in the supergraph fails the build

A checklist that lives in a doc and depends on the agent reading and following it is a soft constraint. Soft constraints fail at scale.

V2 Issue 5 — Auto-merge "off for now" is the wrong default

If the 15 lifecycle agents are doing real work, then human re-review of a green agent-passed PR is wasted dev effort, which violates the brief's "no dev effort" constraint. Either the agents are trustworthy enough to merge low-risk classes or the agents aren't doing real work.

V2 fix: Risk-tier the auto-merge policy:

Tier Policy Applies to
Tier 0 Auto-merge on green Docs-only, cred-agent-rules rule additions that pass canary, generated code from @cred/generators
Tier 1 Auto-merge after 2 agent approvals + 1h soak Non-DB feature work in cred-web-commercial, cred-api-commercial excluding migrations
Tier 2 Human required Migrations, security-sensitive paths, anything labeled arch-review, anything in cred-agent-rules/rules/0001-0010

The current "humans always merge" posture is the most expensive policy possible.

V2 Issue 6 — cred-agent-rules self-sync via post-merge hook = unbounded blast radius

Today: a bad merge to cred-agent-rules/main ships to every developer's environment in every repo on their next git pull, with no canary, no rollout staging, no documented kill switch. CI in every repo also picks up the new rules on its next run.

This is the agentic-tooling equivalent of pushing straight to prod. Rule 0011 prevents auto-merge on cred-agent-rules, but that's not enough.

V2 fix:

  1. Versioning + pinning — repos pin to cred-agent-rules@v1.4.2, not main. Bumps are PRs, not silent.
  2. Canary cohort — new rule versions roll out to 1 repo for 24h, then 3 repos, then org-wide.
  3. Kill switch — a single env var or rule field (status: disabled) immediately neutralizes a bad rule org-wide without a revert PR propagating.
  4. Telemetry on rule firings — count how often each rule blocks something, what % of blocks were overridden, time-to-first-block from version bump (early indicator of false-positive storm).

V2 Issue 7 — The 15 lifecycle agents are a catalog, not a system

V1 lists 15 agents but doesn't address:

  • Shared context / memory — do pr_reviewer and architecture_planner share findings, or duplicate analysis?
  • Cost & latency budget — a 1000-LOC PR potentially fans out to 8+ agents. What's the cap? Who pays?
  • Conflict resolution — what if test_builder writes a test that pr_reviewer immediately flags? Loop until consensus, or who wins?
  • Output contract — are findings structured (JSON) or markdown comments? If markdown, you can't aggregate or dedupe across agents.
  • Telemetry — how do you know pr_reviewer catches real bugs vs noise? What's the precision/recall measured against?
  • Versioning — each agent has its own prompt/system message. Where are those versioned, canaried, A/B'd?
  • **repo_learner flooding** — what stops it from opening 30 rule-proposal PRs a week, each plausible but cumulatively unmaintainable?

V2 fix: Define an AgentRun protocol — every agent emits structured findings to a shared artifact (pr-review.json) with severity, confidence, suggested fix, and citation. orchestrate_review (already in the catalog) dedupes and renders one comment, not 15. Wire telemetry to PostHog/BigQuery: per-agent precision (% of findings acted on), median latency, cost. Without this, V1 is flying blind.

V2 Issue 8 — Onboarding is 7 manual steps; that violates "make our lives easier"

Each step has 2–5 sub-steps. For each repo. For each editor. The brief explicitly said "make our lives easier for development in future." V1 adds friction.

V2 fix: Single command — npx @cred/devkit init — that:

  1. Detects the editor(s) installed, applies user rules to each
  2. Configures org-managed MCP servers via SSO (no per-engineer OAuth dance — set up once at org level, devs inherit)
  3. Clones cred-plans to a known location
  4. Bulk-runs install-into-repo.sh for every cloned cred-* repo
  5. Verifies hooks across all repos
  6. Outputs a single status report

The MCP servers themselves are a centralization opportunity — host org-level MCP servers (Linear, GitHub, BigQuery) on Cloud Run with org SSO instead of per-engineer local MCPs. One config to update, not N.

V2 Issue 9 — Editor-agnostic in prose, not in enforcement

V1 supports three editors and renders three rule formats. But there's no:

  • CI check that the three formats stay in sync (drift will happen)
  • Conformance test proving a behavioral rule produces the same agent action in Cursor + Copilot + Claude Code
  • Decision matrix for which editor handles which workflow type

Saying "all three work" without measuring it means two of them silently degrade. You'll end up with a "Cursor is the real one, the others are theoretical" reality — the worst of both worlds (maintenance cost of three, value of one).

V2 fix: Pick a primary, support a secondary, deprecate the third. Or commit to a conformance test harness that runs the same prompt against all three editors weekly and asserts equivalent behavior. Not both.

V2 Issue 10 — Sub-issue → PR mapping is a coupling smell

V1: one sub-issue = one PR; each PR ~200–400 LOC. Under agentic concurrent execution, the unit isn't "PR" — it's "atomic verifiable change." Several sub-issues might fit in one PR if naturally cohesive (one new endpoint + its types + its tests + its docs); one sub-issue might warrant several PRs if genuinely independent layers (DB migration, then resolver, then UI).

The 200–400 LOC rule is a humans-reviewing-PRs heuristic. With agent review, the meaningful number is "what diff size keeps each agent's context window productive?" — depending on the agent and the diff shape, not LOC.

V2 fix: Sub-issue frontmatter declares pr_strategy: single | layered | split. A pr_planner agent decides PR boundaries based on diff coupling, not LOC. The 200–400 LOC band becomes a default, not a rule.

V2 Issue 11 — Plans are static markdown; should be living artifacts

cred-plans stores markdown files with YAML frontmatter. A plan's status field has to be hand-updated. There's no:

  • Auto-link from plan to its Linear Epic and child PRs
  • Auto-update of status based on Linear/PR state
  • Computed view: "all in-progress plans, sorted by last-PR-merged-at"
  • Plan-to-impl traceability (does this PR fulfill which plan section?)

A plan that is a flat MD file is the same fidelity as a Google Doc. We can do better.

V2 fix: Plans authored as MD but stored alongside an auto-derived JSON manifest. A plan-syncer job (cron'd) reads Linear + GitHub and updates the manifest. A small dashboard (Cursor canvas in the IDE, or a tiny Vercel app) renders the live state. Now plans are queryable, not just searchable.

V2 Issue 12 — No measurement = no improvement loop

The V1 Iteration Loop is virtuous in spirit but has no measurement. Across 50 engineers and 7 repos, you don't see misbehavior — it shows up as opaque PR latency or a vague "the agent felt off this week."

V2 fix: Define and instrument concrete KPIs:

KPI What it measures Source
Dedup rate % of new Linear tickets flagged as duplicates by automation, broken down by accepted-as-dup vs override Linear webhook + LLM classifier
Agent precision For pr_reviewer, % of findings acted on (committed change) vs dismissed PR review thread events
Time-to-merge Median hours from PR open → merge, segmented by tier (auto vs human) GitHub Actions
Rule firing rate How often each rule blocks vs allows, per repo Pre-push hook telemetry
Human override rate When an agent says X and a human does ¬X, log it — training signal for the next rule iteration orchestrate_review
Onboarding time Hours from npx @cred/devkit init to first merged PR @cred/devkit telemetry

No metrics → no honest answer to "is this working?"

V2 Issue 13 — Internal contradictions in V1

Two real contradictions to resolve, plus one that resolves on inspection:

  1. 15 agents review automatically vs humans still merge. If review is real, merge should be automated for low-risk classes; if merge needs humans, the agent review is decorative. (See V2 Issue 5.)
  2. Anti-Dup L4 says "search before implementing" vs User Rule #2 "don't ask permission for obvious next steps." An agent given an "obvious" task will skip the dedup search. Resolve by making dedup non-skippable infrastructure (registry/generator), not a soft instruction. (See V2 Issue 4.)
  3. ~~User Rule #2 vs Rule 0015~~ — resolved on inspection. Rule 0015 ("auto-open-pr-no-confirmation") explicitly aligns with User Rule #2: both say the agent should not pause between commit / push / PR, since "the user almost always wants the PR — that's why they asked for the change." Rule 0015 enumerates explicit exceptions (plan-only requests, cred-plans / cred-agent-rules changes, irreversible operations, failed verification) where confirmation genuinely matters. The earlier version of this doc described 0015 as a prevention rule; that was wrong. No change needed.

V2 Issue 14 — The repo split itself may be the disease

V1 acknowledges:

The Relationship Graph Store work, for example, spans cred-api-commercial, cred-model-api, cred-dbt, and lives under the cred-api-commercial/ plans directory even though it touches all four.

Cross-repo work that requires a Level-5 dedup checklist is evidence the boundaries are wrong. V1 papers over polyrepo overhead with cred-plans as a synchronizer. Synchronization is the most expensive shape of integration.

Worth evaluating (not necessarily adopting, but the plan should at least confront it): a Turborepo / Nx monorepo containing cred-api-commercial, cred-filter-api, cred-model-api, cred-web-commercial, cred-platform-kit. cred-dbt likely stays separate (different runtime). Cross-repo plans become single-repo plans. Refactors that span "repos" become single PRs. The dedup checklist Level 5 disappears because the searches all happen in one tree.

If monorepo is off the table, at minimum: federate the GraphQL schema as the source of truth for cross-repo types and require type generation into every consumer. V1 never names federation as load-bearing — V2 should.

V2 Issue 15 — protect-agents-md is the wrong primitive

A rule that says "don't delete things" is a workaround for the absence of:

  • Strong typing on the protected file (machine-checkable, so deletions break a build, not a rule)
  • Append-only storage with audit (commits can't truncate)
  • A retention policy (today "Learned Workspace Facts" is unboundedly append-only — it'll be 10k lines in a year, which the agent can't reason over efficiently)

V2 fix: Convert AGENTS.md learned-facts into structured YAML/JSON entries (one fact per file, or rows in a table) the agent queries by topic, not by reading the whole file. Now you get version control + queryability + bounded growth. The protection rule becomes a CODEOWNERS rule on the directory, not a behavioral instruction.

Concrete Recommendations Ranked by Leverage

  1. Build cred-platform-kit (UI + backend-kit + schema + generators). The missing layer that turns "shared rules" into "shared code." Single highest-leverage change.
  2. Adopt AGENTS.md as the only committed agent doc. Stop rendering to 3 formats; require tools to read AGENTS.md. Cuts surface area in half.
  3. Federation / schema registry as Level-5 dedup. Any new cross-repo type must originate in the schema source, generated everywhere else.
  4. Risk-tier auto-merge. Tier 0 on by default; we're paying for review and not consuming it.
  5. Replace the dedup checklist with infrastructure (Linear webhooks, generators, registry-backed search). Process is brittle; infra is durable.
  6. Version + canary + kill-switch cred-agent-rules. Pinning, not main-tracking. Telemetry on rule firings.
  7. Concurrent sub-issue execution by default. depends_on DAG, parallel cloud-agent dispatch.
  8. **npx @cred/devkit init** — collapse the 7-step setup to one command.
  9. Define and instrument the KPIs (dedup rate, agent precision, override rate, onboarding time). Without these, the iteration loop is anecdotal.
  10. Confront the polyrepo question. Either commit to monorepo migration as a 2026 plan, or commit to federation + schema registry as the cross-repo dedup spine. Don't do neither.

What V1 Gets Right (for calibration)

  • The four-stage lifecycle (Discover → Plan → Execute → Capture) is a sound mental model
  • Rule frontmatter with enforcement levels (pre-push / agent-only / advisory) is the right primitive
  • cred-plans as a discovery surface is a real improvement over plans-in-Notion
  • The 15-agent catalog is comprehensive (it just needs orchestration / telemetry / versioning underneath)
  • Honest caveats sections like this one are unusually mature — most plans of this type pretend the system is finished

V1 is a strong process layer. It needs a V1 of a platform layer underneath it to deliver on what the brief actually asked for.

Honest Caveats

  • **cred-agent-rules is V1.** See cred-agent-rules/CHANGELOG.md for shipped vs WIP. The installer flow is real; the auto-merge gate is intentionally disabled globally; some lifecycle agents (repo_learner, cross_repo_learner) are newer and still being calibrated.
  • Not every repo has the seed PR merged yet. As of this writing, cred-data-eng workspace repos (cred-dbt, cred-model) have local .cursor/rules/ files but .agent-rules/ from cred-agent-rules may not be installed yet. Run Step 5 to install.
  • MCP setup varies. The list above reflects what's enabled on senior engineers' machines. Some servers (e.g., Vercel, Supabase) only matter if your repo touches those systems — skip what's irrelevant.
  • Skills repo locations. The clone paths in Step 3 (credinvest/cred-cursor-skills, credinvest/cred-claude-skills) are the convention; verify the actual URLs with the Platform Core team if they're not where you expect.
  • VS Code parity is real but uneven. Copilot agent mode handles MCP and .github/copilot-instructions.md natively, but its agent UX still trails Cursor's (e.g., no equivalent of Cursor Skills, weaker plan-mode flow). Claude Code is closer to Cursor on agent UX but is terminal-first. If you're new and want the smoothest path, start with Cursor; switch later if you have a strong VS Code preference.
  • Auto-merge is off. Don't expect the pr_merger agent to merge anything for you. Humans still drive merge for the foreseeable future.

Iteration Loop

Rules are not one-and-done. The right loop:

  1. Observe misbehavior or repeated friction
  2. Articulate the desired behavior in concrete, testable terms
  3. Write the smallest rule that produces it
  4. Test by prompting cold (new chat, no extra context)
  5. Trim ruthlessly — agents respect short rules more than long ones

When a personal rule earns its keep across multiple repos, promote it to a workspace rule. When a workspace rule pays off across multiple repos, PR it into cred-agent-rules for the whole org. The cross_repo_learner agent automates parts of this — but humans still drive the promotion decision.

The best rules are the ones you forget you wrote, because the agent just does the right thing now.

References

CRED repos

  • [credinvest/cred-agent-rules](https://github.com/credinvest/cred-agent-rules) — shared rule library, routing, agent catalog
  • [credinvest/cred-plans](https://github.com/credinvest/cred-plans) — centralized plans, auto-published from agent chats
  • [credinvest/cred-wiki](https://github.com/credinvest/cred-wiki) — engineering wiki (look for the Standards for AI-Assisted Engineering page)
  • cred-agent-rules/LAYOUT.md — full directory structure of the shared rule library
  • cred-agent-rules/learning/runbook.md — what to do when a learner agent opens a PR you disagree with

Cursor

VS Code + GitHub Copilot

VS Code + Claude Code

Contributing Back

Found a rule that should be standard? Found a gap in this guide? PR it.

  • Rule → cred-agent-rules/rules/
  • Plan → cred-plans/plans/<repo>/
  • Wiki page → cred-wiki/docs/development/
  • This onboarding doc → wherever it ends up living (likely cred-wiki/docs/development/ or cred-agent-rules/docs/)

Don't let useful patterns live only in your personal settings.