weekly-planning

Weekly planning

State: to-be-approved. Deploy-verified against a live workspace: not yet. Treat Done when below as the acceptance test and review cargo-ai cdk plan before deploying. Make no outcome claim for this skill until it is approved.

The outcome

What to do next stops living in someone's head until the next planning meeting. Every Monday one agent runs, and two things land:

1. The raw dump. A committed script writes last week's git commits, pull requests, initiative inventory, declared infra, and cadence files dated in that week into cadence/log/raw/planning/.md. That is the evidence, and it is never edited by the agent.
2. The recommendation file(s). The agent reads the dump, the workspace (runs, usage, models, through read-only cargo-ai calls), and the initiative files, and writes markdown a human can merge:
   • No active initiatives — one file, cadence/plan/YYYY-Www.md, one pull request titled [cadence] workspace YYYY-Www. It checks what is happening: declared infra, live runs, usage.
   • One or more active initiatives — one file and one pull request per initiative, titled [cadence] YYYY-Www. Two bets do not share a diff.

Then it stops. A human merges. Recommendations are not a deploy: the agent does not edit infra/, does not start a play, and does not merge itself.

This is a scheduled CI workflow plus a hosted agent, collapsed into resources declared in the same project as everything else the workspace runs. The schedule and the repository binding live in infra/weekly-planning/agents/planner.ts, and the instructions beside it in planner.prompt.ts. harness: "claudeCode" is what buys the working tree: the output of a week is a diff across markdown files, and only an agent with a checkout can produce one.

Three properties make it safe enough to run unattended:

• The collection is deterministic. The agent does not fetch PRs. scripts/collect/week.ts does, the same way every Monday, and the agent is told not to improvise that step. Workspace data (runs, usage, what is deployed) comes from named read-only cargo-ai commands at recap time, not from a second fetch inside the collector.
• One pull request per initiative, or one for the workspace. Combining five bets into one diff is how a reviewer merges the loud one and skips the overdue one. Splitting them is the gate.
• The pull request is the gate. The agent has repository write access and no other write path. It cannot email anyone, cannot touch the CRM, cannot run a cargo-ai command that spends or deploys, and cannot merge itself.

Put it in your project

This folder is a worked example: real CDK resources written for some other company. The job is to end up with the code your company would have written, in your project, and an agent does the adapting. If the cargo-cdk skill is in your session it carries the long form of this; if not, this is enough.

1. Install it — the CLI does the copy. From inside the CDK project, cargo-ai cdk add cookbook/weekly-planning writes this example to infra/weekly-planning/ (resources and scripts/) and this procedure to .claude/skills/weekly-planning/. No project yet? cargo-ai cdk init --cookbook weekly-planning && cd && npm install does both; this folder never ships a shell. If you are reading this from the project's .claude/skills/, the install already happened — start at step 2. On a CLI too old to have add, copy this folder in as a sibling of what is there by hand; everything below is unchanged.
2. Reconcile it with what is already declared. If the project already has a GitHub connector or an agents folder, rewire the imports to the existing one and drop the copy; two resources with one slug is a collision at deploy. Append this folder's env needs to the project's .env.example; never overwrite it.
3. Adapt. Work the sections below in order: What should not change is what you argue back about (say what breaks, then do it if they still want it); What you can change is what you offer unprompted (nobody asks for a variant they do not know exists); What you will be asked is the floor, and you derive before you ask. If you are asking more than about four questions you have skipped lookups. Record what you changed and why under a ## Decisions section in your copy of this file.
4. Run the collector by hand once, then plan. npx tsx scripts/weekly-planning/collect/week.ts --dry-run first: it prints the dump and writes nothing. Then drop --dry-run. If it does not produce a raw file locally it will not produce one on a schedule, and that is far cheaper to find out now. Then node --import tsx evals/contract.mjs && npm run check && cargo-ai cdk plan, show the diff, and deploy only on an explicit yes: cargo-ai cdk deploy. Never cdk init --force into a non-empty directory.
5. Verify. Walk Done when line by line and report each with evidence. Deployed cleanly and produced nothing is the normal failure.

What you will be asked

Derive before you ask. An input with a lookup is looked up, not asked. Only the ones marked asked genuinely live in the operator's head.

Checked before moving on, not after the deploy:

• the collector was run by hand once and wrote a real raw file
• cargo-ai cdk check prints agent:weekly-planning bound to # with no trailing subdirectory — the repo is the one holding cadence/, and the GitHub grant can push to it. A trailing in infra/ is the failure to catch here: it roots the harness where there is no node_modules, so the collector cannot run
• scripts/weekly-planning/package.json is present in the project after the install
• cargo-ai whoami names the workspace this recap should read. That is the prompt's first command, and the first scheduled run is what proves the harness sandbox carries a session of its own; if it does not, every pull request says so and the recap lands from the dump
• node --import tsx evals/contract.mjs passes

What you can change

The code is a worked example. These reshapes are expected, and the agent offers them rather than waiting to be asked. Every one costs something; that is what makes it a variation and not the default.

What should not change

However far you adapt, these hold. Ask for one anyway and the agent tells you what breaks, then does it if you still want it, and records why under ## Decisions in your copy of this file.

• The agent does not fetch git; the script does. (scripts/collect/week.ts) A fetch loop an agent re-derives every Monday is a fetch loop that silently changes shape — a window that drifts, a gh flag that quietly widens. The raw dump is the one thing here that has to be byte-identical in its rules every week, because everything downstream is diffed against it. Cargo workspace data is the other half of the week, and it is read at recap time by the agent, not by a cargo-ai loop bolted into the collector.
• Zero active initiatives is one workspace pull request. N active is N pull requests, plus one unplanned only when work outside them is significant. (infra/agents/planner.prompt.ts) Combining them is how a reviewer merges one bet and skips another. Opening a workspace pull request and the initiative ones gives routine unclaimed runs a second home they were not asked to have: they stay in the dump. The unplanned pull request is the exception, and its bar is concrete (more credits than any initiative, a play failing one run in five, a customer or revenue event no initiative claims). Drop it and an unplanned play can burn the week's credits without ever reaching a reviewer.
• The workspace reads are read-only, and they are the CLI. (infra/agents/planner.prompt.ts) §1b names the commands: whoami, what is deployed, run counts and failures, usage. No capabilities block is wired on the agent, because the read path is already in the sandbox and only the prompt can say "read, never execute". orchestration action execute, batch create, cdk deploy and anything that removes are the forbidden half of that list — a planner that can start a batch is a planner that can spend, and a recommendation is not a deploy. If cargo-ai whoami fails, every pull request says so and the recap continues from the git dump; it does not invent the numbers.
• scripts/weekly-planning/package.json stays. (scripts/package.json) It is not decoration. The CDK loader imports every .ts under the project root except directories carrying a package.json; delete it and cargo-ai cdk plan imports the collector and runs git/gh on every plan.
• The harness root stays the directory holding the package.json that declares @cargo-ai/cdk. (infra/agents/planner.ts) That is where node_modules is, so it is the only place npx tsx …/collect/week.ts resolves — and in the scaffolded layout it is the repository root, which is also where cadence/ and initiatives/ live. Check it, do not assume it: cargo-ai cdk check prints the resolved binding, and a line ending in infra/ means the harness was rooted where there is no package.json and no node_modules. The collector then cannot run at all, and Monday reports clean and empty. On a CLI old enough to resolve it that way, pin rootDirectory: "." in the repository block until you upgrade.
• The agent opens pull requests and never merges them. (infra/agents/planner.prompt.ts) The recommendation is what next week's work is chosen from. Remove the review gate and a hallucinated gap, a play misread as idle, or a stuck item filed against the wrong owner becomes the team's next bet.
• Every file opens with a verdict, in a founder's words. (infra/agents/planner.prompt.ts) On track, Behind, At risk or Blocked, then why, then at most three recommendations each with an owner and a day. Without the verdict a reviewer has to read the whole file to learn whether the bet is in trouble, and a plan nobody finishes reading is one nobody acts on.
• Do not invent a number. (infra/agents/planner.prompt.ts) Drop a metrics line rather than carry last week's ARR forward. A made-up delta is worse than no delta, because the plan file is what leadership reads. A CLI read that errors is a note on the PR, not a count you fill in.
• Never edit plan/ or infra/. (infra/agents/planner.prompt.ts) The planner recommends. A pull request that rewires a play is a deploy wearing a plan file's name.

Done when

• --dry-run printed the dump for the previous ISO week, and the run without it wrote cadence/log/raw/planning/.md; running it twice that Monday overwrote the same file
• node --import tsx evals/contract.mjs passes: harness is claudeCode bound to an Anthropic connector and a model, no capability is wired on the agent, there is no Slack action, and no tool wraps git or the CLI
• cargo-ai cdk plan reports the agent, the GitHub and Anthropic connectors and the folder, and does not run git or gh while planning
• with zero active initiatives, the first scheduled run opened exactly one unmerged pull request titled [cadence] workspace whose diff contains the dump and cadence/plan/.md with ## Recommendations
• with N active initiatives, it opened exactly N unmerged pull requests, one per slug, each diff containing the dump and exactly one cadence/plan/-.md — never a second initiative in the same diff — plus one [cadence] unplanned pull request only when work no initiative claims met the bar in the prompt
• every plan file's description and PR body open with the same verdict (On track, Behind, At risk, Blocked, Unplanned, or No active initiatives), and every recommendation names an action and a day
• a re-run the same Monday opened no additional pull request for a target whose ## Recommendations section was already on disk
• no number in a plan file is absent from the raw dump, a metrics file dated that week, or a cargo-ai read the agent actually ran. A CLI read that errors is a note on the PR, not a made-up count

What it costs

The collector talks to git and, when gh is installed, to GitHub from the harness environment. Those calls are not Cargo connector actions.

The recurring cost is the harness run itself, once a week, billed as LLM tokens through the bound Anthropic connector, and it scales with how much the agent reads — the dump, the week's cadence files, the active initiative files, declared infra, and the read-only cargo-ai calls in §1b (whoami, what is deployed, run counts, usage). Those reads are API calls, not connector actions, so they bill nothing. There is no per-record fan-out, and the recap never runs a command that spends.

Composes into

standup (the week's daily logs are evidence this recap reads), call-capture (scribed calls dated in the week are evidence), tam-building and account-scoring (a declared play that did not run is the gap this recap is for).