Best practices

Patterns that work, from teams using IsonForge daily.

Use FORGE.md aggressively

The single highest-leverage thing. A few hundred words at your project root saves the agent from re-learning your conventions every session.

What to put in:

• Surprising decisions. "We don't use lodash. Native JS only." "Drizzle stays. Don't propose Prisma."
• Test commands. "pnpm test for unit, pnpm test:int requires docker compose up."
• Architecture choices. "All API responses go through lib/response.ts."
• Anti-patterns. "Never use raw SQL. Always go through src/db/."

Generate a starter with isonforge init and refine over time.

Plan first for unfamiliar territory

For any change touching >3 files in code you don't know well:

isonforge --permission-mode plan "<task>"

Get the plan. Read it. Then switch off plan mode and execute. The 30 seconds to review the plan beats the 5 minutes to revert a bad patch.

Checkpoint before risky edits

/checkpoint
> [risky task]

If it goes wrong: /rollback restores every file touched since the checkpoint. Free safety net.

Use sub-agents for breadth

Whenever you're about to ask the agent "where is X / who calls Y / map the Z flow," let it spawn task_explore instead. Keeps your main context clean for the actual work.

The system prompt nudges the agent to do this, but you can also ask explicitly:

> use task_explore to map the entire auth flow, then propose the refactor

Match effort to the task

Not everything needs max. Daily defaults:

Switch with /effort mid-session.

Worktrees for parallel features

isonforge -w feature-auth
isonforge -w feature-billing

Two terminals, two worktrees, two features in flight. No context switching, no stash juggling.

Add --bg to either if you want it running while you work elsewhere.

Permission modes match trust level

• default when learning a new repo. Get prompted, learn what the agent does.
• acceptEdits for daily work in a familiar repo.
• auto when you trust the agent broadly but want a floor against dangerous ops.
• plan for high-stakes changes you want to review first.
• bypassPermissions / --yolo for scripts and CI only. Don't make it your interactive default.

Cycle with Shift+Tab per-task.

Verified vs assumed

Always read the agent's summary at the end of a turn. The agent is trained to distinguish:

• Verified: ran a command, read a file, observed an exit code.
• Assumed: believed but didn't check.

If the agent says "I assumed the test framework is pytest," ask it to verify. Don't ship code based on assumed facts.

When to /compact

When the agent starts forgetting things from earlier in the session, or token usage gets heavy:

/compact

Summarizes older turns, keeps recent ones verbatim. Free up context for more work.

Auto-compact triggers around 78% context fill, but manual is faster.

When to /clear

When you're starting a new task that doesn't depend on the previous one. Fresh context = better focus. /clear is cheap.

Stream-of-consciousness prompts work

You don't need a perfectly structured prompt. Describe the symptom, paste the error, mention what you've tried:

> the login route 500s on first request after restart. error says
  "Cannot read property 'id' of undefined" at auth/user.js:42.
  i think it's a race condition with the session middleware but not sure.
  there's a comment in the code that says "TODO: fix race" so probably.

The agent traces it, finds the race, fixes it.

Use --append-system-prompt for project rules

For team-shared rules that should apply EVERY session:

// .isonforge/settings.json
{
  "systemPromptAppend": "Project conventions:\n- All routes use lib/response.ts\n- Validation via Zod\n- Tests required"
}

Check it in. New team members get the same rules.

Background what you can

If a task takes >5 minutes and doesn't need decisions:

isonforge --bg "review every endpoint for auth + rate limiting"

Walk away. Come back in 20 minutes. isonforge logs <id>.

Skills for recurring workflows

If you find yourself typing the same multi-step prompt repeatedly, that's a Skill:

# ~/.isonforge/skills/triage-pr/SKILL.md
---
description: Triage an open PR. Check tests, security, style. Output a review comment.
---

Pull the PR with `gh pr view $0 --json title,body,additions,deletions,files`.
Read the diff with `gh pr diff $0`.
Check tests are present and pass.
Check for security issues.
Check style against our conventions in FORGE.md.

Output a single review comment that I can paste into the PR. Be terse and specific.

Then /triage-pr 123 does the whole thing.

Don't over-edit prompts

The model usually does fine with rough, conversational prompts. Heavy prompt engineering matters less than:

• Having FORGE.md set up.
• Picking the right permission mode.
• Picking the right effort level.
• Verifying the agent's work before merging.

Read tool calls

When the agent does something, the tool box shows the call. Read it. If it's reading auth/wrong-file.py when it should be reading auth/right-file.py, redirect it ("read auth/right-file.py instead"). Catching wrong-direction work early saves a lot of revert.

Test loops

For tight test-driven loops:

> /effort low
> add a test for User.findById that checks the 404 case
> /effort low
> the test should also check the rate-limit case

Low effort + short prompts = fast iteration. Switch to high when you hit a hard bug.