| name | development-agent |
| description | Use whenever the user asks Codex to implement, execute, or ship a plan in this repo, especially requests that include saving to /plans, creating a branch, editing code, updating docs/wiki, running verification, committing, pushing, opening or updating a PR, and restarting dev. Captures the repo's required release workflow, safety boundaries, verification discipline, and PR standards. |
| version | 1.2.0 |
Development Agent
Use this workflow for requests shaped like:
- “implement this plan”
- “PLEASE IMPLEMENT THIS PLAN”
- “save this to /plans, implement, update documentation, commit, push, create a PR, and restart dev”
- “have Codex build this”
- “turn this plan into a PR”
- “finish the implementation and verify it”
This skill is responsible for turning a plan into a safe, reviewable, verified repo change.
The goal is not to make the biggest possible change.
The goal is to ship the smallest complete vertical slice that satisfies the user’s plan without breaking repo conventions.
Operating Principles
-
Plan fidelity over invention
Implement the user’s actual plan. Do not silently replace it with a different architecture, broader rewrite, or unrelated cleanup.
-
Repo safety over speed
Check state before editing, preserve unrelated work, and avoid destructive commands unless explicitly requested.
-
Local patterns over novelty
Prefer existing Prisma, agent, ADK, LangGraph, Jolene, wiki, API, test, and UI patterns before introducing new architecture.
-
Verification must be evidence-based
Do not claim success without naming the exact commands run and their results.
-
Documentation changes with behavior
If behavior, workflow, API shape, agent behavior, route behavior, or developer operation changes, update the relevant docs in the same branch.
-
Human-gated actions stay gated
Autonomous or external actions must remain behind confirmation, review, or approval flows. App-local repairs may use Jolene confirmation cards when supported.
Required Workflow
1. Inspect repo state first
Run:
git status --short --branch
Before editing, identify:
- current branch
- whether the working tree is clean
- unrelated modified files
- untracked files
- pending user work
Do not overwrite, delete, stage, or “fix” unrelated user changes.
If unrelated changes exist:
- work around them when possible
- avoid touching those files unless required by the plan
- mention them in the final response
2. Read repo instructions
Read AGENTS.md before implementation.
Also inspect any referenced local guidance, including:
- README sections relevant to the feature
- wiki pages relevant to the subsystem
- existing architecture notes
- route/API entrypoints
- Prisma schema or migrations when data changes
- existing tests for the touched subsystem
- nearby components, hooks, services, agents, or utilities
If AGENTS.md references external Next.js docs that are unavailable, follow existing local patterns instead of guessing.
3. Save the plan before implementation
If the user provides or references a plan, save it under plans/ before coding.
Use a clear uppercase filename.
Examples:
plans/SLACK_COMMAND_CENTER_CONFIRMATION_FLOW.md
plans/JOLENE_DAILY_REVIEW_QUEUE.md
plans/LINKEDIN_CONTENT_QUALITY_GATE.md
The saved plan should preserve:
- the user’s intent
- implementation scope
- acceptance criteria
- safety constraints
- verification expectations
- known exclusions
Do not let the saved plan drift into a new product proposal.
4. Create a feature branch
Create a feature branch from the current base unless the user explicitly says not to.
Use a concise branch name.
Examples:
git switch -c feature/slack-command-center-confirmation
git switch -c fix/linkedin-content-quality-gate
git switch -c docs/jolene-agent-runbook
Do not switch branches if doing so would risk losing uncommitted user work.
5. Establish the implementation map
Before editing, identify:
- files likely to change
- tests likely to change
- docs likely to change
- routes/API surfaces affected
- data model or migration impact
- agent/tooling boundaries affected
- gated actions or safety checks required
Favor a small vertical slice over a broad horizontal rewrite.
A complete vertical slice usually includes:
- source change
- focused test coverage
- documentation update when behavior changes
- verification commands
- PR notes
6. Implement the smallest complete slice
Implement only what is needed to satisfy the plan.
Do:
- follow existing local naming and file conventions
- keep changes narrow and reviewable
- preserve deterministic fallbacks
- preserve existing public APIs unless the plan requires a change
- keep external actions gated
- prefer explicit types and clear boundaries
- add comments only when they clarify non-obvious behavior
Do not:
- rewrite unrelated architecture
- rename files casually
- introduce new libraries without a clear need
- change formatting across untouched files
- remove tests to make verification pass
- weaken safety gates
- bypass confirmation flows
- commit secrets or generated local state
- silently skip plan requirements
7. Add focused tests
Add or update tests for new behavior.
Prioritize:
- unit tests for deterministic utilities
- component tests for UI behavior
- route/API tests for server behavior
- agent/tool tests for prompt, routing, safety, and fallback behavior
- regression tests for fixed bugs
- edge cases from the plan
Tests should prove the behavior, not merely snapshot implementation details.
Preserve existing deterministic fallbacks.
8. Update documentation
Update README, wiki, docs, runbooks, or architecture notes when requested or when behavior changes.
Documentation should explain:
- what changed
- why it exists
- how to use it
- safety boundaries
- verification or operational notes
- known limitations
Keep docs factual. Do not turn docs into marketing copy.
9. Run verification
Run the most relevant verification commands.
Required baseline:
git diff --check
npx tsc --noEmit --pretty false
npm run build
Run targeted tests for touched areas:
npx vitest run <relevant-test-files> --config vitest.config.ts
Run broader tests when the change touches shared behavior:
npx vitest run --config vitest.config.ts
Run React Doctor when React code changed or feature completion warrants it:
npx react-doctor@latest --verbose --diff
If Prisma/schema changed, include the repo’s existing Prisma verification or migration checks.
If routes/API surfaces changed, manually verify the affected route/API where practical.
Do not claim a command passed if it was not run.
If a command fails:
- inspect the failure
- fix plan-related failures
- rerun the command
- if still failing because of pre-existing unrelated issues, document that clearly with the failing command and relevant error summary
10. Review the diff before staging
Inspect:
git diff
git status --short
Confirm:
- only intended files changed
- plan file is included
- docs are included when required
- tests are included when appropriate
- no secrets, local env files, logs, screenshots with private data, or generated junk are staged
- unrelated user changes are not staged
11. Commit safely
Stage only intended files.
Use a terse commit message.
Examples:
git commit -m "Add Slack confirmation gate"
git commit -m "Improve LinkedIn content quality checks"
git commit -m "Document Jolene review workflow"
If GPG signing times out, retry with:
git -c commit.gpgsign=false commit -m "<message>"
Mention the unsigned retry in the final response.
12. Push the feature branch
Push the branch:
git push -u origin <branch-name>
If push fails because of remote, auth, or branch issues, report the exact blocker.
Do not force push unless explicitly requested and safe.
13. Open or update the PR
Open or update a PR targeting main.
Use staff-pr-writer standards.
The PR body must include:
- product/architecture why
- subsystem changes
- implementation notes
- data or migration impact
- safety boundaries
- exact verification commands and results
- reviewer guide
- known limitations
- screenshots or route notes when UI changed
Replace thin PR bodies instead of appending to them.
Do not open a PR with a vague body such as:
“Implemented plan.”
14. Restart dev and verify changed surfaces
Restart the local dev server when requested or when the change affects runtime behavior.
Verify changed routes, pages, or API surfaces.
Capture:
- route checked
- expected behavior
- result
- any remaining limitation
Do not say “dev restarted” unless it actually restarted successfully.
Repo Rules
- Read
AGENTS.md first.
- Follow existing local patterns when external docs are unavailable.
- Do not revert unrelated user changes.
- Do not stage unrelated files.
- Do not remove or weaken tests to pass verification.
- Do not introduce new architecture when local patterns are sufficient.
- Do not bypass confirmation gates for external or risky actions.
- Keep autonomous/external actions gated.
- App-local repairs may use Jolene confirmation cards when supported.
- Use existing Prisma, agent, ADK, LangGraph, Jolene, route, wiki, and test patterns before introducing new ones.
- If GPG signing times out, retry with
git -c commit.gpgsign=false commit ... and mention it in the final response.
Safety Boundaries
Never commit:
.env files- secrets
- API keys
- tokens
- private emails
- recruiter names
- private job URLs
- raw application data
- screenshots containing sensitive personal data
- local database files unless explicitly intended
- generated caches
- build output unless the repo requires it
Before PR creation, check for accidental private content in:
- plans
- docs
- screenshots
- fixtures
- seed data
- test snapshots
- logs
Job Search OS may contain sensitive job-search context. Public or semi-public artifacts must use aggregated, anonymized, or synthetic data unless the user explicitly asks otherwise.
Failure Handling
If implementation cannot be completed fully, do not hide the failure.
Return:
- what was completed
- what could not be completed
- exact blocker
- files changed
- verification run
- verification failures
- safest next step
Do not claim:
- committed if no commit exists
- pushed if push failed
- PR opened if PR creation failed
- tests passed if they failed or were skipped
- dev restarted if it did not restart
Publishable Final Response
At the end, report only useful facts.
Include:
- branch name
- plan path
- commit hash
- PR link
- changed areas
- verification commands and results
- dev restart result
- known limitations
- any unrelated working-tree changes left untouched
Example:
Implemented and opened PR: <PR link>
Branch: feature/slack-command-center-confirmation
Plan: plans/SLACK_COMMAND_CENTER_CONFIRMATION_FLOW.md
Commit: abc1234
Changed:
- Added confirmation gate for Slack-triggered risky actions
- Updated Jolene routing tests
- Documented the workflow in the wiki
Verification:
- npx vitest run ... --config vitest.config.ts — passed
- npx tsc --noEmit --pretty false — passed
- npm run build — passed
- git diff --check — passed
- npx react-doctor@latest --verbose --diff — passed
Dev:
- Restarted successfully
- Verified /command-center and /api/slack/actions
Notes:
- Left unrelated local changes untouched: <files>
If something failed, be explicit:
Implemented the code and tests, but PR creation failed because GitHub auth was unavailable.
Branch: feature/...
Commit: abc1234
Verification:
- Tests passed
- Typecheck passed
- Build failed because of a pre-existing error in <file>; not caused by this change
Next step:
- Re-run PR creation after GitHub auth is restored.
Completion Criteria
The task is complete only when one of these is true:
Fully complete
- plan saved
- branch created
- implementation done
- docs updated when required
- tests added or updated
- verification run
- commit created
- branch pushed
- PR opened or updated
- dev restarted and checked when required
- final response includes evidence
Partially complete with blocker
- safe partial work is completed
- blocker is clearly identified
- no false success claims are made
- next step is obvious
Editor Bias
Default bias:
- Smaller change is better than broader rewrite.
- Verified change is better than impressive change.
- Existing repo pattern is better than new architecture.
- Clear blocker is better than fake completion.
- Reviewable PR is better than clever implementation.
