Onboard Plan
Productivityonboard-planOnboard Plan is an Agent Skill for productivity published in the jackfranklin/dotfiles repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Gives a fresh agent a plan, audits it for comprehension gaps, and verifies technical assumptions against the codebase before implementation begins. Spawns a single sub-agent to perform both checks and presents the findings.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/jackfranklin/dotfiles/blob/HEAD/claude/skills/onboard-plan/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/onboard-plan, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Plan Onboarding
Use this skill when you have a plan saved as a GitHub Issue and want to begin a fresh implementation session with zero ambiguity and validated technical assumptions.
Step 1: Resolve the Plan Issue
The skill argument may be:
- A GitHub issue number: fetch it directly with
gh issue view <number> --json title,body. - A fuzzy description (e.g. "the plan about auth refactor"): search with
gh issue list --search "[PLAN] <description>" --state open --json number,titleand pick the best match by title similarity. If more than one is plausible, ask the user to choose before proceeding.
Step 2: Read the Plan
Read the full issue body. Do not summarise or paraphrase it at this stage.
Step 3: Spawn the Verification Sub-agent
Spawn a single research or self subagent to audit the plan. It receives the raw plan text and this prompt:
You are onboarding onto a new implementation plan. Your goal is to identify comprehension gaps in the plan text and verify its technical assumptions against the live codebase.
PLAN:
{PLAN_CONTENT}
Perform the following tasks:
1. COMPREHENSION AUDIT:
Identify any places where an engineer would not know exactly what to do or what something means (e.g. undefined terms, ambiguous steps, sequencing issues).
Formulate a list of questions for the user in the format:
Q: [question]
Where: [exact quote/step]
2. CODEBASE VERIFICATION:
Cross-reference the files, APIs, databases, and configuration keys mentioned in the plan with the live codebase.
Identify any:
- Stale/incorrect assumptions about existing APIs, exports, or data schemas.
- Mismatches in configuration or file layouts.
- Hidden dependencies/prerequisites omitted from the plan.
Constraints:
- Do not suggest or make changes to the codebase.
- Rely only on live codebase verification (do not guess).
- Focus only on technical blocking issues.
Return the results in two clean sections: "Comprehension Gaps" and "Codebase Verification". No preamble, no summary.
Step 4: Present to the User
Display the results returned by the subagent. Invite the user to answer the questions and resolve the codebase findings before beginning implementation.