The Planning Agent is PlanOpticon's AI-powered system for synthesizing knowledge graph content into structured planning artifacts. It takes extracted entities and relationships from video analyses, document ingestions, and other sources, then uses LLM reasoning to produce project plans, PRDs, roadmaps, task breakdowns, GitHub issues, and more.
4
5
---
6
7
## How It Works
8
9
The Planning Agent operates through a three-stage pipeline:
10
11
### 1. Context Assembly
12
13
The agent gathers context from all available sources:
14
15
- **Knowledge graph** -- entity counts, types, relationships, and planning entities from the loaded KG
16
- **Query engine** -- used to pull stats, entity lists, and relationship data for prompt construction
17
- **Provider manager** -- the configured LLM provider used for generation
18
- **Prior artifacts** -- any artifacts already generated in the session (skills can chain off each other)
19
- **Conversation history** -- accumulated chat messages when running in interactive mode
20
21
This context is bundled into an `AgentContext` dataclass that is shared across all skills.
22
23
### 2. Skill Selection
24
25
When the agent receives a user request, it determines which skills to run:
26
27
**LLM-driven planning (with provider).** The agent constructs a prompt that includes the knowledge base summary, all available skill names and descriptions, and the user's request. The LLM returns a JSON array of skill names to execute in order, along with any parameters. For example, given "Create a project plan and break it into tasks," the LLM might select `["project_plan", "task_breakdown"]`.
28
29
**Keyword fallback (without provider).** If no LLM provider is available, the agent falls back to simple keyword matching. It splits each skill name on underscores and checks whether any of those words appear in the user's request. For example, the request "generate a roadmap" would match the `roadmap` skill because "roadmap" appears in both the request and the skill name.
30
31
### 3. Execution
32
33
Selected skills are executed sequentially. Each skill:
34
35
1. Checks `can_execute()` to verify the required context is available (by default, both a knowledge graph and an LLM provider must be present)
36
2. Pulls relevant data from the knowledge graph via the query engine
37
3. Constructs a detailed prompt for the LLM with extracted context
38
4. Calls the LLM and parses the response
39
5. Returns an `Artifact` object containing the generated content
40
41
Each artifact is appended to `context.artifacts`, making it available to subsequent skills. This enables chaining -- for example, `task_breakdown` can feed into `github_issues`.
42
43
---
44
45
## AgentContext
46
47
The `AgentContext` dataclass is the shared state object that connects all components of the planning agent system.
48
49
```python
50
@dataclass
51
class AgentContext:
52
knowledge_graph: Any = None # KnowledgeGraph instance
53
query_engine: Any = None # GraphQueryEngine instance
54
provider_manager: Any = None # ProviderManager instance
Artifacts are the currency of the agent system. They can be:
90
91
- Displayed directly in the Companion REPL
92
- Exported to disk via the `artifact_export` skill
93
- Pushed to external tools via the `cli_adapter` skill
94
- Chained into other skills (e.g., task breakdown feeds into GitHub issues)
95
96
---
97
98
## Skills Reference
99
100
The agent ships with 11 built-in skills. Each skill is a class that extends `Skill` and self-registers at import time via `register_skill()`.
101
102
### project_plan
103
104
**Description:** Generate a structured project plan from knowledge graph.
105
106
Pulls the full knowledge graph context (stats, entities, relationships, and planning entities grouped by type) and asks the LLM to produce a comprehensive project plan with:
| `assignee_role` | string | Role needed to perform the task |
163
164
**Artifact type:** `task_list` | **Format:** json
165
166
### github_issues
167
168
**Description:** Generate GitHub issues from task breakdown.
169
170
Converts tasks into GitHub-ready issue objects. If a `task_list` artifact exists in the context, it is used as input. Otherwise, minimal issues are generated from the planning entities directly.
171
172
Each issue includes a formatted body with description, priority, estimate, and dependencies, plus labels derived from the task priority.
173
174
The skill also provides a `push_to_github(issues_json, repo)` function that shells out to the `gh` CLI to create actual issues. This is used by the `cli_adapter` skill.
175
176
**Artifact type:** `issues` | **Format:** json
177
178
### requirements_chat
179
180
**Description:** Interactive requirements gathering via guided questions.
181
182
Generates a structured requirements questionnaire based on the knowledge graph context. The questionnaire contains 8-12 targeted questions, each with:
| `context` | string | Why this question matters |
190
191
The skill also provides a `gather_requirements(context, answers)` method that takes the completed Q&A and synthesizes structured requirements (goals, constraints, priorities, scope).
The skill checks whether the target CLI is available on the system and includes that status in the output. Commands are generated in dry-run mode by default.
**Description:** Generate a GitHub wiki from knowledge graph and artifacts.
272
273
Generates a complete GitHub wiki structure as a dictionary of page names to markdown content. Creates:
274
275
- **Home** page with entity type counts and links
276
- **_Sidebar** navigation with entity types and artifacts
277
- **Type index pages** with tables of entities per type
278
- **Individual entity pages** with descriptions, outgoing/incoming relationships, and source occurrences
279
- **Artifact pages** for any generated planning artifacts
280
281
The skill also provides standalone functions `write_wiki(pages, output_dir)` to write pages to disk and `push_wiki(wiki_dir, repo)` to push directly to a GitHub wiki repository.
282
283
**Artifact type:** `wiki` | **Format:** markdown
284
285
---
286
287
## CLI Usage
288
289
### One-shot execution
290
291
Run the agent with a request string. The agent selects and executes appropriate skills automatically.
292
293
```bash
294
# Generate a project plan
295
planopticon agent "Create a project plan" --kb ./results
296
297
# Generate a PRD
298
planopticon agent "Write a PRD for the authentication system" --kb ./results
299
300
# Break down into tasks
301
planopticon agent "Break this into tasks and estimate effort" --kb ./results
302
```
303
304
### Export artifacts to disk
305
306
Use `--export` to write generated artifacts to a directory:
307
308
```bash
309
planopticon agent "Create a full project plan with tasks" --kb ./results --export ./output
310
```
311
312
### Interactive mode
313
314
Use `-I` for a multi-turn session where you can issue multiple requests:
315
316
```bash
317
planopticon agent -I --kb ./results
318
```
319
320
In interactive mode, the agent supports:
321
322
- Free-text requests (executed via LLM skill selection)
323
- `/plan` -- shortcut to generate a project plan
324
- `/skills` -- list available skills
325
- `quit`, `exit`, `q` -- end the session
326
327
### Provider and model options
328
329
```bash
330
# Use a specific provider
331
planopticon agent "Create a roadmap" --kb ./results -p anthropic
332
333
# Use a specific model
334
planopticon agent "Generate a PRD" --kb ./results --chat-model gpt-4o
335
```
336
337
### Auto-discovery
338
339
If `--kb` is not specified, the agent uses `KBContext.auto_discover()` to find knowledge graphs in the workspace.
340
341
---
342
343
## Using Skills from the Companion REPL
344
345
The Companion REPL provides direct access to agent skills through slash commands. See the [Companion guide](companion.md) for full details.
346
347
| Companion Command | Skill Executed |
348
|---|---|
349
| `/plan` | `project_plan` |
350
| `/prd` | `prd` |
351
| `/tasks` | `task_breakdown` |
352
| `/run SKILL_NAME` | Any registered skill by name |
353
354
When executed from the Companion, skills use the same `AgentContext` that powers the chat mode. This means:
355
356
- The knowledge graph loaded at startup is automatically available
357
- The active LLM provider (set via `/provider` or `/model`) is used for generation
358
- Generated artifacts accumulate across the session, enabling chaining
Based on the knowledge graph, the main goals are...
391
392
planopticon> /plan
393
--- Project Plan (project_plan) ---
394
...
395
396
planopticon> /tasks
397
--- Task Breakdown (task_list) ---
398
...
399
400
planopticon> /run github_issues
401
--- GitHub Issues (issues) ---
402
[
403
{"title": "Set up authentication service", ...},
404
...
405
]
406
407
planopticon> /run artifact_export
408
--- Export Manifest (export_manifest) ---
409
{
410
"artifact_count": 3,
411
"output_dir": "plan",
412
"files": [...]
413
}
414
```
415
416
### Skill chaining
417
418
Skills that produce artifacts make them available to subsequent skills automatically:
419
420
1. `/tasks` generates a `task_list` artifact
421
2. `/run github_issues` detects the existing `task_list` artifact and converts its tasks into GitHub issues
422
3. `/run cli_adapter` takes the most recent artifact and generates `gh issue create` commands
423
4. `/run artifact_export` writes all accumulated artifacts to disk with a manifest
424
425
This chaining works both in the Companion REPL and in one-shot agent execution, since the `AgentContext.artifacts` list persists for the duration of the session.