01
Run locally
Persist task scope, verify the owned worktree, and execute one bounded attempt with explicit outcomes.
Task scopeWorktree ownershipBounded execution
Local-first agentic engineering
AgentForge
A private engineering CLI that turns bounded agent attempts into inspectable evidence while keeping validation, human approval, and GitHub publication behind explicit boundaries.
- Context
- Independent developer tool
- Role
- Product architecture & engineering
- Status
- Private · In development
- Runtime
- Local CLI and owned Git worktrees
- Stack
- TypeScript · Node.js · SQLite · Git · GitHub APIs
01 / Product overview
A guarded path from task to draft pull request.
AgentForge separates execution from proof. Every boundary asks for the evidence needed by the next one.
02
Prove the revision
Bind validation checks, repository fingerprints, and review material to the exact candidate revision.
Validation profilesRevision evidenceReview package
03
Publish deliberately
Require explicit human authorization before pushing an approved snapshot and opening a draft pull request.
Human approvalDraft PR onlyAmbiguity recovery
02 / Engineering architecture
Evidence crosses boundaries; authority does not.
The local CLI coordinates policy and durable state around an owned Git worktree. Agent execution is bounded, validation is revision-specific, and GitHub mutation remains outside the run until approval is verified.
SQLite stores tasks, attempts, events, checks, review packages, approvals, and publication records so recovery does not depend on an agent’s final message.
Local execution boundary
Control plane
CLI + policy
Owns lifecycle transitions and rejects unsupported state changes
Repository boundary
Git worktree
Isolates the task and exposes the exact candidate revision
Execution boundary
Agent attempt
Runs once within bounded time, scope, and cancellation controls
Evidence boundary
Validate + review
Packages trusted checks and provenance for the current revision
Durable local state
SQLite evidence store
Lifecycle records, attempts, events, validation results, approvals, and publication state
Human-authorized external boundary
GitHub draft PR
Push the approved snapshot, reconcile ambiguous results, and create a draft pull request—never merge
03 / Engineering highlights
Reliability designed around exact evidence.
A successful process exit is only one event. The system preserves the stronger proof needed for review, approval, and recovery.
Human authorization binds the exact publication snapshot
The approval challenge is separate from execution and review. Changed credentials, repository state, metadata, or review artifacts invalidate the publication path.
Guarded lifecycle
Policy prevents generic status changes from skipping required validation, review, or approval evidence.
Revision-bound validation
Trusted profiles, ordered checks, and before-and-after fingerprints keep passing results attached to the revision that produced them.
Fail-closed recovery
Timeouts, cancellations, stale claims, and uncertain remote outcomes enter explicit recovery paths instead of being treated as success.
Constrained publication
Deterministic commit construction and same-repository branch controls limit GitHub writes to an approved draft pull request.
04 / Technical challenges
Design decisions at trust boundaries.
- Execution is not validationA zero exit code and final message do not create test evidence or approve a revision.
- Validation is not authorizationPassing checks can make a revision reviewable, but cannot permit remote mutation.
- Approval is snapshot-specificThe publication gate rechecks the evidence and identity attached to the approved candidate.
- Timeout is ambiguousA timed-out push or PR request is reconciled before any retry to avoid duplicate or conflicting writes.
- Local does not mean unguardedWorktree containment, credential boundaries, durable claims, and bounded repair reduce accidental repository damage.