GigiKit Guides

The Developer Agent

The developer agent (spawned as fullstack-developer) is the implementation specialist in GigiKit’s pipeline. It reads a phase file produced by the planner, implements the code exactly as specified, and hands off to the tester.

Role

The developer agent does one thing: implement code. It does not plan, test, or review. Its scope is bounded by the phase file it receives and the file ownership list within it.

When the Developer Is Invoked

Cook spawns the developer agent after plan approval. In sequential mode, one developer handles phases one at a time. In --parallel mode, multiple developer agents run concurrently on non-overlapping phase files.

The orchestrator delegation prompt always specifies:

Spawn fullstack-developer sub-agent:

"Execute phase-02 of the JWT auth plan.

Phase file: /Users/dev/my-app/plans/260305-0912-jwt-auth/phase-02-endpoints.md
Work context: /Users/dev/my-app
Reports: /Users/dev/my-app/plans/reports/

File ownership:
- src/routes/auth.ts (create)
- src/middleware/jwt-verify.ts (create)
- src/types/auth.ts (create)

Do NOT modify any files outside this list."

Implementation Standards

The developer agent follows GigiKit’s development rules throughout:

Code quality:

  • Files must stay under 200 lines — split into focused modules when approaching the limit
  • Use kebab-case for file names (jwt-verify.ts, not jwtVerify.ts)
  • Add descriptive comments for complex logic
  • Handle edge cases and error scenarios explicitly
  • Use try/catch with proper error propagation

After each file:

  • Run the project’s compile/typecheck command to catch errors immediately
  • Fix type errors before moving to the next file
# Verify after each implementation step
npm run typecheck
# or
tsc --noEmit

Modularization Rule

If any single file would exceed 200 lines, the developer must split it before proceeding:

src/services/
├── auth-service.ts           # Core auth logic
├── auth-token-manager.ts     # Token creation & validation
└── auth-session-store.ts     # Session persistence

The developer checks existing modules before creating new ones — no duplicate utilities.

Updating Existing Files

The developer updates files in place. It never creates a new “enhanced” version of an existing file. The pattern is:

  1. Read the existing file completely
  2. Identify the minimal change needed
  3. Apply the targeted edit
  4. Verify compile still passes

Completion Report

After implementing all phase steps, the developer produces a concise report:

## Phase Implementation Report

### Files Modified
- src/routes/auth.ts (created, 87 lines)
- src/middleware/jwt-verify.ts (created, 54 lines)
- src/types/auth.ts (created, 23 lines)

### Tasks Completed
- [x] Login endpoint with bcrypt password check
- [x] Logout endpoint with token invalidation
- [x] JWT verification middleware
- [x] TypeScript interfaces for auth types

### Tests Status
- Typecheck: pass
- Build: pass

### Next Steps
- Phase 03 (tests) is now unblocked

Next Steps