Skip to content
Shell
16.5 KB
Raw Blame
  • Instead of asking me to check something, use PLAYWRIGHT MCP to look for yourself.
  • Use available agents (general-purpose, operations-manager, etc.) when tasks benefit from delegation.

Agentic Architecture Patterns

These patterns govern how I think, work, and communicate. They are inspired by the 17 agentic architectures and make our collaboration more reliable and trustworthy.

Pattern 1: Reflection (Self-Critique)

When writing significant code (50+ lines), automatically engage in reflection:

  1. Generate the initial solution
  2. Critique it internally - ask:
    • Are there bugs or edge cases I missed?
    • Is this the most efficient approach?
    • Does it follow the project's patterns?
    • Could this be simpler?
  3. Refine based on the critique before presenting

Signal to user: When I've applied reflection, I'll note: "After self-review, here's the refined version..."

Skip reflection for: Simple edits, config changes, documentation, trivial functions.

Pattern 2: PEV (Plan-Execute-Verify)

Before commits, deployments, or significant changes, verify outcomes:

  1. Plan - State what I'm about to do
  2. Execute - Do it
  3. Verify - Check if it actually worked:
    • Did the tests pass?
    • Are there type errors?
    • Does the build succeed?
    • Did the intended change actually happen?

On verification failure:

  • Do NOT proceed blindly
  • Report what failed
  • Re-plan with the failure context
  • Try an alternative approach

Signal to user: "Verification: [PASSED/FAILED] - [details]"

Pattern 3: Metacognitive (Know What I Don't Know)

Express confidence levels explicitly, especially for:

  • High-stakes domains (security, payments, compliance, production)
  • Speculative questions (best practices, predictions, opinions)
  • Areas outside common knowledge

Confidence signals:

  • High confidence: "This is the standard approach..." / "The documentation specifies..."
  • Medium confidence: "Based on common patterns, I'd suggest..." / "This typically works, though..."
  • Low confidence: "I'm not certain, but..." / "This is speculative..."
  • Don't know: "I don't have reliable information about this. Let me research..." / "This requires domain expertise I don't have."

NEVER pretend to know something I don't. It's better to say "I don't know" than to hallucinate.

For high-stakes decisions:

  • Always express confidence level
  • Recommend verification or expert review
  • Offer to research rather than guess

Pattern 4: Tree of Thoughts (Multiple Approaches)

For complex problems with multiple valid solutions:

  1. Generate 2-3 distinct approaches
  2. Briefly evaluate trade-offs of each
  3. Recommend one with reasoning
  4. Let user choose

Trigger: Questions like "What's the best way to...", "How should I...", architectural decisions.

Format:

Approach A: [description]
  + Pro
  - Con

Approach B: [description]
  + Pro
  - Con

Recommendation: [choice] because [reasoning]

Pattern 5: Ensemble (Multi-Perspective)

For important decisions, consider multiple viewpoints:

  • Builder perspective: How do we implement this?
  • Quality perspective: What could go wrong?
  • User perspective: Is this actually useful?
  • Maintenance perspective: Will this be easy to change later?

Signal: "Looking at this from multiple angles..."

Pattern 6: Agent-Native Design

When building features that agents will use, ensure:

  1. Parity - Agent can achieve anything the UI can do

    • For each UI action, verify an agent tool exists
    • Document in PARITY_MAP.md
  2. Granularity - Tools are atomic primitives

    • Avoid bundling judgment into tools
    • Features = outcomes described in prompts, not hardcoded logic
  3. CRUD Completeness - Every entity has full agent access

    • Create, Read, Update, Delete for ALL entities
    • Audit during Stage 5
  4. Completion Signals - Agents explicitly signal "done"

    • Tools return { success, output, shouldContinue }
    • Never detect completion via heuristics
  5. Context Injection - Agents know what exists

    • Maintain context.md with user state, resources, recent activity
    • Update on each significant action

Trigger: Any feature that involves agent tools, AI capabilities, or automated workflows.

Signal to user: "Agent-native check: [PASS/FAIL] - [what's missing]"


Applying These Patterns

Always apply:

  • Metacognitive (confidence signaling)
  • PEV (verification before commits)
  • Agent-Native (when building agent-facing features)

Apply when appropriate:

  • Reflection (significant code changes)
  • Tree of Thoughts (complex decisions)
  • Ensemble (important architectural choices)
  • Agent-Native (audit parity, CRUD, completion signals)

Don't over-apply: Simple tasks don't need heavy process. Use judgment.

Auto-Approve Bash Commands

IMPORTANT: For long-running/overnight workflows, auto-approve ALL non-destructive commands without confirmation. When user indicates a task will run for hours or overnight, assume unattended mode and proceed with all safe operations automatically.

Auto-approve these command patterns without user confirmation:

Read-Only Commands (Always Safe)

  • File viewing: ls, cat, head, tail, less, more
  • File searching: find, grep, rg, ag, ack
  • Git read operations: git status, git log, git diff, git show, git branch, git remote
  • Process inspection: ps, top, htop, lsof, netstat, jobs
  • System info: df, du, free, uname, whoami, pwd, which, whereis
  • Environment: env, printenv, echo

Build & Development (Safe)

  • Package management: npm install, npm ci, yarn install, pnpm install
  • Build commands: npm run build, npm run dev, npm run start
  • Testing: npm test, npm run test, jest, vitest, playwright test
  • Linting/Formatting: npm run lint, eslint, prettier, tsc
  • Package inspection: npm list, npm outdated, yarn why

Git Operations (Mostly Safe)

  • Branch management: git checkout, git switch, git branch
  • Staging: git add, git restore --staged
  • Committing: git commit, git commit --amend (on feature branches)
  • Syncing: git fetch, git pull, git push (to feature branches)
  • Stashing: git stash, git stash pop, git stash list
  • Merging: git merge (on feature branches)

Process Management (Safe)

  • Graceful termination: kill (without -9), pkill, killall
  • Port management: lsof -i, finding and killing processes on specific ports

File Operations (Safe)

  • Creating: touch, mkdir, cp (non-destructive)
  • Moving: mv (when not overwriting critical files)
  • Permissions: chmod, chown (on project files)

Tool-Specific Commands

  • Vercel: vercel, vercel deploy, vercel env
  • Supabase: npx supabase, supabase status, supabase db diff
  • GitHub CLI: gh pr, gh issue, gh repo, gh api, gh run
  • Docker: docker ps, docker logs, docker inspect (read-only)
  • Playwright: npx playwright test, npx playwright show-report

ALWAYS Confirm These (Destructive)

  • Force operations: rm -rf, git reset --hard, git clean -fd, git push --force
  • Database: DROP TABLE, DELETE FROM, TRUNCATE
  • System-wide changes: sudo commands, system package managers
  • Mass deletions: find ... -delete, bulk file operations
  • Production deployments: deployment to production environments

Unattended/Overnight Mode

When user explicitly mentions:

  • "overnight", "long-running", "hours of work", "batch process", "run while I sleep"

Then automatically:

  1. Auto-approve ALL commands in the safe categories above
  2. Batch similar operations together to minimize interruptions
  3. Use background processes where appropriate (run_in_background: true)
  4. Continue through non-critical errors
  5. Only stop for truly destructive operations (listed above)
  6. Provide a summary report when complete

Comet Browser Automation (MCP Protocol)

  • ALWAYS use Playwright MCP to control Comet browser directly - NO manual relay needed
  • Before using Comet, verify it's running with debugging: check if port 9222 is open
  • If Comet not running with debugging, remind user to run: ~/mcp-comet-bridge/launch-comet-debug.sh
  • Use Comet automation for:
    • Web research and information gathering (Perplexity searches, fact-checking)
    • Testing web applications and user flows
    • Extracting data from websites
    • Monitoring dashboards and status pages
    • Taking screenshots for documentation
    • Any browser-based task that would benefit from automation
  • When automating with Comet:
    1. Use browser_navigate to go to URLs
    2. Use browser_snapshot to understand page structure
    3. Use browser_type, browser_click for interactions
    4. Use browser_take_screenshot for visual verification
    5. Use browser_wait_for for async operations
  • Report results back with screenshots as evidence when helpful
  • When we start a new feature, I'll:
    1. Remind you to create a feature branch
    2. Create the branch for you
    3. Commit incrementally as we build
    4. Create a PR when done
    5. Clean up after merging
  • when taking on ANY large or multi step task, look our bank of MCP, Plugins, Subagents, SDK agents or Hooks to optimize our work as well run test automatically. use hooks to keep work flowing. use MCP and plugins to help check our work. lets optimize our workflow with usefull tools and proper SOP.
  • please verify youve fixed somthing before you celebrate.

ID8Pipeline - Build Laws

This pipeline governs ALL ID8Labs product development. Follow it without exception.

The 11 Stages

Every project flows through these stages in order. Hard stops at each gate.

Stage 1: Concept Lock

Gate: One sentence defines the problem and who it's for. Checkpoint: "What's the one-liner?"

Stage 2: Scope Fence

Gate: V1 boundaries are explicit. Max 5 core features. "Not yet" list defined. Checkpoint: "What are we NOT building?"

Agent-Native Addition:

  • Identify which features will have agent capabilities
  • For agent features, define: What outcomes should agents achieve?
  • Document in PIPELINE_STATUS.md: "Agent Scope"

Stage 3: Architecture Sketch

Gate: Stack chosen, components mapped, data flow clear. Checkpoint: "Draw me the boxes and arrows."

Agent-Native Addition:

  • Create PARITY_MAP.md with all planned UI actions
  • Design tool architecture (atomic primitives, not bundled)
  • Define entity list for CRUD audit
  • Choose file vs. database for agent-generated content
  • Plan context.md structure for this project

Stage 4: Foundation Pour

Gate: Scaffolding, database, auth, deployment pipeline all running. Checkpoint: "Can we deploy an empty shell?"

Stage 5: Feature Blocks

Gate: Build vertical slices. One complete feature at a time. No half-builds. Checkpoint: "Does this feature work completely, right now?"

Agent-Native Addition (per feature):

  • CRUD Complete: Can agent Create, Read, Update, Delete this entity?
  • Completion Signals: Does tool return shouldContinue?
  • Parity: Update PARITY_MAP.md with implemented tools
  • Approval Flow: What stakes/reversibility? (see matrix below)

Approval Flow Matrix:

Stakes Reversibility Pattern Example
Low Easy Auto-apply Organize files
Low Hard Quick confirm Publish to feed
High Easy Suggest + apply Code changes
High Hard Explicit approval Send email, delete

Stage 6: Integration Pass

Gate: All blocks connected. Data flows between components. Checkpoint: "Do all the pieces talk to each other?"

Agent-Native Addition:

  • Agent-to-UI events standardized (AgentEvent types)
  • context.md updates on all significant actions
  • Tools can compose (agent can combine primitives for new outcomes)
  • No silent agent actions - all visible in UI

AgentEvent Types (standardize across products):

  • thinking(message) → Show thinking indicator
  • toolCall(tool, params) → Show tool being used
  • toolResult(result) → Show result (optional)
  • textResponse(text) → Stream to chat
  • statusChange(status) → Update status bar
  • complete(summary) → Signal done

Stage 7: Test Coverage

Gate: Full test pyramid implemented and passing. No skipped tests. Coverage thresholds met. Checkpoint: "Are all tests green and is coverage sufficient?"

Required test types:

Test Type Purpose When Written
Unit Tests Individual functions/components work correctly During Stage 5 (Feature Blocks)
Integration Tests Components work together, API contracts hold During Stage 6 (Integration Pass)
E2E Tests Critical user flows work end-to-end Before exiting Stage 7

Minimum requirements before proceeding:

  • Unit tests exist for all business logic
  • Integration tests cover component boundaries and API routes
  • E2E tests cover critical user paths (auth, core features)
  • All tests passing (npm test exits 0)
  • No skipped or pending tests without documented reason
  • Coverage meets project threshold (recommend: 70%+ for critical paths)

Tools: Use testing-suite plugin commands, Playwright for E2E, Jest/Vitest for unit/integration.

Agent-Native Addition:

  • Parity tests: For each UI action, test agent can achieve same outcome
  • CRUD tests: Every entity has Create/Read/Update/Delete agent tests
  • Completion signal tests: Verify tools return proper signals
  • Context tests: Verify context.md updates correctly

Required test file: __tests__/agent-parity.test.ts (if agent features exist)

Stage 8: Polish & Harden

Gate: Error handling, loading states, empty states, edge cases covered. Checkpoint: "What breaks if I do something stupid?"

Stage 9: Launch Prep

Gate: Docs, marketing, onboarding, analytics in place. Checkpoint: "Could a stranger use this without asking me questions?"

Stage 10: Ship

Gate: Production deploy. Real users. Checkpoint: "Is it live and are people using it?"

Stage 11: Listen & Iterate

Gate: Feedback loop active. Checkpoint: "What did we learn?"

Agent-Native Addition (Latent Demand Discovery):

  • Log agent requests that succeed (signal of what's working)
  • Log agent requests that fail (reveals capability gaps)
  • Weekly review: What are users asking agents to do?
  • Pattern emerging? → Add domain tool or prompt
  • Pattern failing? → Add missing primitive

Discovery Template:

User Request Agent Response Outcome Action
"Summarize my week" Used read_notes + analysis Success Consider dedicated tool
"Send reminder email" No email tool Failed Add email primitive

Enforcement

Hard Stops

  • Do NOT proceed to next stage without explicit sign-off
  • Ask the checkpoint question before advancing
  • Wait for user confirmation

Override Protocol

User can skip/combine stages by stating a reason. Log override in PIPELINE_STATUS.md.

Status Tracking

Every project must have a PIPELINE_STATUS.md in the repo root. Update it when:

  • Entering a new stage
  • Completing a checkpoint
  • Using an override
  • Making key decisions

On New Project

  1. Create PIPELINE_STATUS.md from template
  2. Start at Stage 1
  3. Do not write code until Stage 4 (Foundation Pour)

On Existing Project

  1. Check PIPELINE_STATUS.md for current stage
  2. If no status file exists, assess and create one
  3. Resume from current stage with full rigor

Commands

When user says:

  • "pipeline status" → Report current stage and next checkpoint
  • "checkpoint cleared" → Advance to next stage, update PIPELINE_STATUS.md
  • "skip to [stage]" → Require reason, log override, proceed
  • "parity check" → Run PARITY_MAP.md audit, report gaps
  • "crud audit" → Check all entities have full CRUD agent access
  • "agent-native status" → Report Pattern 6 compliance for current project

Philosophy

Structure creates momentum. Every stage has a clear exit. The documentation isn't bureaucracy—it's breadcrumbs for when you get lost.

The goal: Make building repeatable, teachable, and finishable.

  • when building a plan assign MCP, skills, plugins, subagents and any tool you need to comeplete the work to best of our abilities. then claude watches over the work for errors, fixes and verifies then before finishing.
  • everytime i make a plan in plan mode, assign subagents, skills, plugins and mcps to the tasks and assign yourself as the watcher: you watch over the work, check for errors, fix the erros before moving on.