Fennec Planning

Modes

Mode: Plan (Full SDLC Pipeline)

For substantial features that need scoping before implementation.

Step 1: Capture Intent as Idea

const idea = await fennec.ideas.create({
  projectId: "<id>",
  title: "Add user authentication with JWT",
  content: "Full auth system: register, login, token refresh, middleware, role-based access control..."
});
// Save idea.id for next steps

Step 2: AI Elaboration

Let Fennec's AI generate clarifying questions and answer them automatically based on codebase context:

const { round, summary } = await fennec.ideas.elaborateAI(idea.id);
// round contains generated questions + answers
// summary is a text overview of elaboration findings

Review the summary. If more depth is needed, call elaborateAI again — it creates additional rounds.

Step 3: Synthesize into Proposal

Convert elaboration answers into a formal proposal:

const { proposal } = await fennec.ideas.synthesize(idea.id);
// proposal has: id, title, description, status: "draft"

Review the proposal description. If it looks good:

await fennec.proposals.submit(proposal.id);    // draft → pending
await fennec.proposals.approve(proposal.id);   // pending → approved

To reject with feedback:

await fennec.proposals.reject(proposal.id, "Need to include rate limiting");

Step 4: Decompose into Tasks

Use the AI decomposer to break the approved work into parallelizable tasks:

const { planId } = await fennec.projects.decompose(projectId, {
  intent: proposal.description,  // or refine the intent
  strategy: "auto"  // "parallel" | "sequential" | "auto"
});

This spawns an agent that explores the codebase. Poll for completion:

const result = await fennec.projects.getDecomposition(projectId, planId);
// result.status: "running" | "completed"
// result.plan: { tasks, rationale, estimatedComplexity, warnings }

IMPORTANT: The decomposition runs async. Poll every 10-15 seconds until status === "completed". The plan has a 10-minute cache TTL.

Step 5: Review and Approve Plan

Once status === "completed", review result.plan:

• Check task count, parallel groups, file scopes
• Review warnings (file overlap, missing scopes)
• Verify rationale makes sense

Approve to create actual tasks + task group + dependencies:

const materialized = await fennec.projects.approveDecomposition(projectId, planId);
// materialized: { groupId, tasks: [{id, title, localId}], dependenciesCreated, decisionId }

Step 6: Log Decision

The decomposer auto-logs a decision on approval, but log additional context:

await fennec.decisions.log({
  projectId,
  title: "Approved auth implementation plan",
  rationale: "6 tasks in 3 parallel groups, estimated moderate complexity",
  context: "Decomposed from idea " + idea.id
});

Mode: Quick (Direct Task Creation)

For clear, well-defined work that doesn't need elaboration.

// Create task group
const group = await fennec.taskGroups.create({
  projectId,
  title: "Sprint 5 — API cleanup",
  description: "Fix response formats and add validation"
});

// Create tasks in the group
const t1 = await fennec.tasks.create({
  projectId,
  title: "Standardize error response format",
  description: "All endpoints return { error: string, code?: string }",
  priority: "medium",
  groupId: group.id
});

const t2 = await fennec.tasks.create({
  projectId,
  title: "Add Zod validation to task routes",
  priority: "low",
  groupId: group.id
});

// Add dependencies if needed
await fennec.tasks.createDependency(t2.id, t1.id);  // t2 depends on t1

Mode: Add (Extend Existing Work)

// List existing task groups to find where new work fits
const groups = await fennec.taskGroups.list({ projectId });

// Create new idea for the addition
const idea = await fennec.ideas.create({
  projectId,
  title: "Add WebSocket authentication",
  content: "Extend existing auth to validate WS connections..."
});

// Quick AI elaboration
const { summary } = await fennec.ideas.elaborateAI(idea.id);

// If small enough, create task directly in existing group
const task = await fennec.tasks.create({
  projectId,
  title: "Add auth middleware to WebSocket upgrade handler",
  description: summary,
  priority: "high",
  groupId: groups[0].id  // add to existing group
});

Mode: Review (Status Overview)

// Full project status
const [ideas, tasks, groups, missions, decisions] = await Promise.all([
  fennec.ideas.list({ projectId }),
  fennec.tasks.list({ projectId }),
  fennec.taskGroups.list({ projectId }),
  fennec.missions.list({ projectId }),
  fennec.decisions.list({ projectId }),
]);

// Task breakdown by status
const byStatus = {};
for (const t of tasks) {
  byStatus[t.status] = (byStatus[t.status] || 0) + 1;
}
return { ideas: ideas.length, tasks: byStatus, groups: groups.length, missions: missions.length, decisions: decisions.length };

Mode: Decide (Log Decisions)

Every significant trade-off should be recorded:

await fennec.decisions.log({
  projectId,
  title: "Use JWT over session cookies for auth",
  rationale: "Stateless, works with microservices, simpler for API-first architecture. Trade-off: token revocation requires allowlist.",
  context: "Decided during auth planning, see idea <id>"
});

Search past decisions for context:

const results = await fennec.knowledge.search("authentication approach", { projectId, limit: 5 });

Mission Orchestration (Large Efforts)

For work spanning multiple task groups with validation checkpoints, use missions:

// List missions for a project
const missions = await fennec.missions.list({ projectId });

// Get mission details with milestones and events
const detail = await fennec.missions.get(missionId);
// detail: { mission, milestones, events }

// Start mission execution
await fennec.missions.start(missionId);

// Monitor milestones
const milestones = await fennec.missions.listMilestones(missionId);

// Pause/resume if needed
await fennec.missions.pause(missionId);
await fennec.missions.resume(missionId);

Key Principles

1. Everything in the DB — no local markdown files for PM state
2. AI-first — use elaborateAI and decompose instead of manual breakdown
3. Log decisions — every trade-off gets fennec.decisions.log
4. Review before approve — always review decomposition plans before approveDecomposition
5. Use knowledge search — fennec.knowledge.search for past context before planning
6. Visible in dashboard — all entities show up in the web UI at their respective pages

Quick Reference

Plan:    ideas.create → ideas.elaborateAI → ideas.synthesize → proposals.submit/approve → projects.decompose → projects.approveDecomposition
Quick:   taskGroups.create → tasks.create (with groupId) → tasks.createDependency
Add:     ideas.create → ideas.elaborateAI → tasks.create (in existing group)
Review:  ideas.list + tasks.list + taskGroups.list + missions.list + decisions.list
Decide:  decisions.log + knowledge.search