|
3551b80…
|
noreply
|
1 |
# Planning Agent |
|
3551b80…
|
noreply
|
2 |
|
|
3551b80…
|
noreply
|
3 |
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. |
|
3551b80…
|
noreply
|
4 |
|
|
3551b80…
|
noreply
|
5 |
--- |
|
3551b80…
|
noreply
|
6 |
|
|
3551b80…
|
noreply
|
7 |
## How It Works |
|
3551b80…
|
noreply
|
8 |
|
|
3551b80…
|
noreply
|
9 |
The Planning Agent operates through a three-stage pipeline: |
|
3551b80…
|
noreply
|
10 |
|
|
3551b80…
|
noreply
|
11 |
### 1. Context Assembly |
|
3551b80…
|
noreply
|
12 |
|
|
3551b80…
|
noreply
|
13 |
The agent gathers context from all available sources: |
|
3551b80…
|
noreply
|
14 |
|
|
3551b80…
|
noreply
|
15 |
- **Knowledge graph** -- entity counts, types, relationships, and planning entities from the loaded KG |
|
3551b80…
|
noreply
|
16 |
- **Query engine** -- used to pull stats, entity lists, and relationship data for prompt construction |
|
3551b80…
|
noreply
|
17 |
- **Provider manager** -- the configured LLM provider used for generation |
|
3551b80…
|
noreply
|
18 |
- **Prior artifacts** -- any artifacts already generated in the session (skills can chain off each other) |
|
3551b80…
|
noreply
|
19 |
- **Conversation history** -- accumulated chat messages when running in interactive mode |
|
3551b80…
|
noreply
|
20 |
|
|
3551b80…
|
noreply
|
21 |
This context is bundled into an `AgentContext` dataclass that is shared across all skills. |
|
3551b80…
|
noreply
|
22 |
|
|
3551b80…
|
noreply
|
23 |
### 2. Skill Selection |
|
3551b80…
|
noreply
|
24 |
|
|
3551b80…
|
noreply
|
25 |
When the agent receives a user request, it determines which skills to run: |
|
3551b80…
|
noreply
|
26 |
|
|
3551b80…
|
noreply
|
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"]`. |
|
3551b80…
|
noreply
|
28 |
|
|
3551b80…
|
noreply
|
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. |
|
3551b80…
|
noreply
|
30 |
|
|
3551b80…
|
noreply
|
31 |
### 3. Execution |
|
3551b80…
|
noreply
|
32 |
|
|
3551b80…
|
noreply
|
33 |
Selected skills are executed sequentially. Each skill: |
|
3551b80…
|
noreply
|
34 |
|
|
3551b80…
|
noreply
|
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) |
|
3551b80…
|
noreply
|
36 |
2. Pulls relevant data from the knowledge graph via the query engine |
|
3551b80…
|
noreply
|
37 |
3. Constructs a detailed prompt for the LLM with extracted context |
|
3551b80…
|
noreply
|
38 |
4. Calls the LLM and parses the response |
|
3551b80…
|
noreply
|
39 |
5. Returns an `Artifact` object containing the generated content |
|
3551b80…
|
noreply
|
40 |
|
|
3551b80…
|
noreply
|
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`. |
|
3551b80…
|
noreply
|
42 |
|
|
3551b80…
|
noreply
|
43 |
--- |
|
3551b80…
|
noreply
|
44 |
|
|
3551b80…
|
noreply
|
45 |
## AgentContext |
|
3551b80…
|
noreply
|
46 |
|
|
3551b80…
|
noreply
|
47 |
The `AgentContext` dataclass is the shared state object that connects all components of the planning agent system. |
|
3551b80…
|
noreply
|
48 |
|
|
3551b80…
|
noreply
|
49 |
```python |
|
3551b80…
|
noreply
|
50 |
@dataclass |
|
3551b80…
|
noreply
|
51 |
class AgentContext: |
|
3551b80…
|
noreply
|
52 |
knowledge_graph: Any = None # KnowledgeGraph instance |
|
3551b80…
|
noreply
|
53 |
query_engine: Any = None # GraphQueryEngine instance |
|
3551b80…
|
noreply
|
54 |
provider_manager: Any = None # ProviderManager instance |
|
3551b80…
|
noreply
|
55 |
planning_entities: List[Any] = field(default_factory=list) |
|
3551b80…
|
noreply
|
56 |
user_requirements: Dict[str, Any] = field(default_factory=dict) |
|
3551b80…
|
noreply
|
57 |
conversation_history: List[Dict[str, str]] = field(default_factory=list) |
|
3551b80…
|
noreply
|
58 |
artifacts: List[Artifact] = field(default_factory=list) |
|
3551b80…
|
noreply
|
59 |
config: Dict[str, Any] = field(default_factory=dict) |
|
3551b80…
|
noreply
|
60 |
``` |
|
3551b80…
|
noreply
|
61 |
|
|
3551b80…
|
noreply
|
62 |
| Field | Purpose | |
|
3551b80…
|
noreply
|
63 |
|---|---| |
|
3551b80…
|
noreply
|
64 |
| `knowledge_graph` | The loaded `KnowledgeGraph` instance; provides access to entities, relationships, and graph operations | |
|
3551b80…
|
noreply
|
65 |
| `query_engine` | A `GraphQueryEngine` for running structured queries (stats, entities, neighbors, relationships) | |
|
3551b80…
|
noreply
|
66 |
| `provider_manager` | The `ProviderManager` that handles LLM API calls across providers | |
|
3551b80…
|
noreply
|
67 |
| `planning_entities` | Entities classified into the planning taxonomy (goals, requirements, risks, etc.) | |
|
3551b80…
|
noreply
|
68 |
| `user_requirements` | Structured requirements gathered from the `requirements_chat` skill | |
|
3551b80…
|
noreply
|
69 |
| `conversation_history` | Accumulated chat messages for interactive sessions | |
|
3551b80…
|
noreply
|
70 |
| `artifacts` | All artifacts generated during the session, enabling skill chaining | |
|
3551b80…
|
noreply
|
71 |
| `config` | Arbitrary configuration overrides | |
|
3551b80…
|
noreply
|
72 |
|
|
3551b80…
|
noreply
|
73 |
--- |
|
3551b80…
|
noreply
|
74 |
|
|
3551b80…
|
noreply
|
75 |
## Artifacts |
|
3551b80…
|
noreply
|
76 |
|
|
3551b80…
|
noreply
|
77 |
Every skill returns an `Artifact` dataclass: |
|
3551b80…
|
noreply
|
78 |
|
|
3551b80…
|
noreply
|
79 |
```python |
|
3551b80…
|
noreply
|
80 |
@dataclass |
|
3551b80…
|
noreply
|
81 |
class Artifact: |
|
3551b80…
|
noreply
|
82 |
name: str # Human-readable name (e.g., "Project Plan") |
|
3551b80…
|
noreply
|
83 |
content: str # The generated content (markdown, JSON, etc.) |
|
3551b80…
|
noreply
|
84 |
artifact_type: str # Type identifier: "project_plan", "prd", "roadmap", etc. |
|
3551b80…
|
noreply
|
85 |
format: str = "markdown" # Content format: "markdown", "json", "mermaid" |
|
3551b80…
|
noreply
|
86 |
metadata: Dict[str, Any] = field(default_factory=dict) |
|
3551b80…
|
noreply
|
87 |
``` |
|
3551b80…
|
noreply
|
88 |
|
|
3551b80…
|
noreply
|
89 |
Artifacts are the currency of the agent system. They can be: |
|
3551b80…
|
noreply
|
90 |
|
|
3551b80…
|
noreply
|
91 |
- Displayed directly in the Companion REPL |
|
3551b80…
|
noreply
|
92 |
- Exported to disk via the `artifact_export` skill |
|
3551b80…
|
noreply
|
93 |
- Pushed to external tools via the `cli_adapter` skill |
|
3551b80…
|
noreply
|
94 |
- Chained into other skills (e.g., task breakdown feeds into GitHub issues) |
|
3551b80…
|
noreply
|
95 |
|
|
3551b80…
|
noreply
|
96 |
--- |
|
3551b80…
|
noreply
|
97 |
|
|
3551b80…
|
noreply
|
98 |
## Skills Reference |
|
3551b80…
|
noreply
|
99 |
|
|
3551b80…
|
noreply
|
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()`. |
|
3551b80…
|
noreply
|
101 |
|
|
3551b80…
|
noreply
|
102 |
### project_plan |
|
3551b80…
|
noreply
|
103 |
|
|
3551b80…
|
noreply
|
104 |
**Description:** Generate a structured project plan from knowledge graph. |
|
3551b80…
|
noreply
|
105 |
|
|
3551b80…
|
noreply
|
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: |
|
3551b80…
|
noreply
|
107 |
|
|
3551b80…
|
noreply
|
108 |
1. Executive Summary |
|
3551b80…
|
noreply
|
109 |
2. Goals and Objectives |
|
3551b80…
|
noreply
|
110 |
3. Scope |
|
3551b80…
|
noreply
|
111 |
4. Phases and Milestones |
|
3551b80…
|
noreply
|
112 |
5. Resource Requirements |
|
3551b80…
|
noreply
|
113 |
6. Risks and Mitigations |
|
3551b80…
|
noreply
|
114 |
7. Success Criteria |
|
3551b80…
|
noreply
|
115 |
|
|
3551b80…
|
noreply
|
116 |
**Artifact type:** `project_plan` | **Format:** markdown |
|
3551b80…
|
noreply
|
117 |
|
|
3551b80…
|
noreply
|
118 |
### prd |
|
3551b80…
|
noreply
|
119 |
|
|
3551b80…
|
noreply
|
120 |
**Description:** Generate a product requirements document (PRD) / feature spec. |
|
3551b80…
|
noreply
|
121 |
|
|
3551b80…
|
noreply
|
122 |
Filters planning entities to those of type `requirement`, `feature`, and `constraint`, then asks the LLM to generate a PRD with: |
|
3551b80…
|
noreply
|
123 |
|
|
3551b80…
|
noreply
|
124 |
1. Problem Statement |
|
3551b80…
|
noreply
|
125 |
2. User Stories |
|
3551b80…
|
noreply
|
126 |
3. Functional Requirements |
|
3551b80…
|
noreply
|
127 |
4. Non-Functional Requirements |
|
3551b80…
|
noreply
|
128 |
5. Acceptance Criteria |
|
3551b80…
|
noreply
|
129 |
6. Out of Scope |
|
3551b80…
|
noreply
|
130 |
|
|
3551b80…
|
noreply
|
131 |
If no pre-filtered entities match, the LLM derives requirements from the full knowledge graph context. |
|
3551b80…
|
noreply
|
132 |
|
|
3551b80…
|
noreply
|
133 |
**Artifact type:** `prd` | **Format:** markdown |
|
3551b80…
|
noreply
|
134 |
|
|
3551b80…
|
noreply
|
135 |
### roadmap |
|
3551b80…
|
noreply
|
136 |
|
|
3551b80…
|
noreply
|
137 |
**Description:** Generate a product/project roadmap. |
|
3551b80…
|
noreply
|
138 |
|
|
3551b80…
|
noreply
|
139 |
Focuses on planning entities of type `milestone`, `feature`, and `dependency`. Asks the LLM to produce a roadmap with: |
|
3551b80…
|
noreply
|
140 |
|
|
3551b80…
|
noreply
|
141 |
1. Vision and Strategy |
|
3551b80…
|
noreply
|
142 |
2. Phases (with timeline estimates) |
|
3551b80…
|
noreply
|
143 |
3. Key Dependencies |
|
3551b80…
|
noreply
|
144 |
4. A Mermaid Gantt chart summarizing the timeline |
|
3551b80…
|
noreply
|
145 |
|
|
3551b80…
|
noreply
|
146 |
**Artifact type:** `roadmap` | **Format:** markdown |
|
3551b80…
|
noreply
|
147 |
|
|
3551b80…
|
noreply
|
148 |
### task_breakdown |
|
3551b80…
|
noreply
|
149 |
|
|
3551b80…
|
noreply
|
150 |
**Description:** Break down goals into tasks with dependencies. |
|
3551b80…
|
noreply
|
151 |
|
|
3551b80…
|
noreply
|
152 |
Focuses on planning entities of type `goal`, `feature`, and `milestone`. Returns a JSON array of task objects, each containing: |
|
3551b80…
|
noreply
|
153 |
|
|
3551b80…
|
noreply
|
154 |
| Field | Type | Description | |
|
3551b80…
|
noreply
|
155 |
|---|---|---| |
|
3551b80…
|
noreply
|
156 |
| `id` | string | Task identifier (e.g., "T1", "T2") | |
|
3551b80…
|
noreply
|
157 |
| `title` | string | Short task title | |
|
3551b80…
|
noreply
|
158 |
| `description` | string | Detailed description | |
|
3551b80…
|
noreply
|
159 |
| `depends_on` | list | IDs of prerequisite tasks | |
|
3551b80…
|
noreply
|
160 |
| `priority` | string | `high`, `medium`, or `low` | |
|
3551b80…
|
noreply
|
161 |
| `estimate` | string | Effort estimate (e.g., "2d", "1w") | |
|
3551b80…
|
noreply
|
162 |
| `assignee_role` | string | Role needed to perform the task | |
|
3551b80…
|
noreply
|
163 |
|
|
3551b80…
|
noreply
|
164 |
**Artifact type:** `task_list` | **Format:** json |
|
3551b80…
|
noreply
|
165 |
|
|
3551b80…
|
noreply
|
166 |
### github_issues |
|
3551b80…
|
noreply
|
167 |
|
|
3551b80…
|
noreply
|
168 |
**Description:** Generate GitHub issues from task breakdown. |
|
3551b80…
|
noreply
|
169 |
|
|
3551b80…
|
noreply
|
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. |
|
3551b80…
|
noreply
|
171 |
|
|
3551b80…
|
noreply
|
172 |
Each issue includes a formatted body with description, priority, estimate, and dependencies, plus labels derived from the task priority. |
|
3551b80…
|
noreply
|
173 |
|
|
3551b80…
|
noreply
|
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. |
|
3551b80…
|
noreply
|
175 |
|
|
3551b80…
|
noreply
|
176 |
**Artifact type:** `issues` | **Format:** json |
|
3551b80…
|
noreply
|
177 |
|
|
3551b80…
|
noreply
|
178 |
### requirements_chat |
|
3551b80…
|
noreply
|
179 |
|
|
3551b80…
|
noreply
|
180 |
**Description:** Interactive requirements gathering via guided questions. |
|
3551b80…
|
noreply
|
181 |
|
|
3551b80…
|
noreply
|
182 |
Generates a structured requirements questionnaire based on the knowledge graph context. The questionnaire contains 8-12 targeted questions, each with: |
|
3551b80…
|
noreply
|
183 |
|
|
3551b80…
|
noreply
|
184 |
| Field | Type | Description | |
|
3551b80…
|
noreply
|
185 |
|---|---|---| |
|
3551b80…
|
noreply
|
186 |
| `id` | string | Question identifier (e.g., "Q1") | |
|
3551b80…
|
noreply
|
187 |
| `category` | string | `goals`, `constraints`, `priorities`, or `scope` | |
|
3551b80…
|
noreply
|
188 |
| `question` | string | The question text | |
|
3551b80…
|
noreply
|
189 |
| `context` | string | Why this question matters | |
|
3551b80…
|
noreply
|
190 |
|
|
3551b80…
|
noreply
|
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). |
|
3551b80…
|
noreply
|
192 |
|
|
3551b80…
|
noreply
|
193 |
**Artifact type:** `requirements` | **Format:** json |
|
3551b80…
|
noreply
|
194 |
|
|
3551b80…
|
noreply
|
195 |
### doc_generator |
|
3551b80…
|
noreply
|
196 |
|
|
3551b80…
|
noreply
|
197 |
**Description:** Generate technical documentation, ADRs, or meeting notes. |
|
3551b80…
|
noreply
|
198 |
|
|
3551b80…
|
noreply
|
199 |
Supports three document types, selected via the `doc_type` parameter: |
|
3551b80…
|
noreply
|
200 |
|
|
3551b80…
|
noreply
|
201 |
| `doc_type` | Output Structure | |
|
3551b80…
|
noreply
|
202 |
|---|---| |
|
3551b80…
|
noreply
|
203 |
| `technical_doc` (default) | Overview, Architecture, Components and Interfaces, Data Flow, Deployment and Configuration, API Reference | |
|
3551b80…
|
noreply
|
204 |
| `adr` | Title, Status (Proposed), Context, Decision, Consequences, Alternatives Considered | |
|
3551b80…
|
noreply
|
205 |
| `meeting_notes` | Meeting Summary, Key Discussion Points, Decisions Made, Action Items (with owners), Open Questions, Next Steps | |
|
3551b80…
|
noreply
|
206 |
|
|
3551b80…
|
noreply
|
207 |
**Artifact type:** `document` | **Format:** markdown |
|
3551b80…
|
noreply
|
208 |
|
|
3551b80…
|
noreply
|
209 |
### artifact_export |
|
3551b80…
|
noreply
|
210 |
|
|
3551b80…
|
noreply
|
211 |
**Description:** Export artifacts in agent-ready formats. |
|
3551b80…
|
noreply
|
212 |
|
|
3551b80…
|
noreply
|
213 |
Writes all artifacts accumulated in the context to a directory structure. Each artifact is written to a file based on its type: |
|
3551b80…
|
noreply
|
214 |
|
|
3551b80…
|
noreply
|
215 |
| Artifact Type | Filename | |
|
3551b80…
|
noreply
|
216 |
|---|---| |
|
3551b80…
|
noreply
|
217 |
| `project_plan` | `project_plan.md` | |
|
3551b80…
|
noreply
|
218 |
| `prd` | `prd.md` | |
|
3551b80…
|
noreply
|
219 |
| `roadmap` | `roadmap.md` | |
|
3551b80…
|
noreply
|
220 |
| `task_list` | `tasks.json` | |
|
3551b80…
|
noreply
|
221 |
| `issues` | `issues.json` | |
|
3551b80…
|
noreply
|
222 |
| `requirements` | `requirements.json` | |
|
3551b80…
|
noreply
|
223 |
| `document` | `docs/<name>.md` | |
|
3551b80…
|
noreply
|
224 |
|
|
3551b80…
|
noreply
|
225 |
A `manifest.json` is written alongside, listing all exported files with their names, types, and formats. |
|
3551b80…
|
noreply
|
226 |
|
|
3551b80…
|
noreply
|
227 |
**Artifact type:** `export_manifest` | **Format:** json |
|
3551b80…
|
noreply
|
228 |
|
|
3551b80…
|
noreply
|
229 |
Accepts an `output_dir` parameter (defaults to `plan/`). |
|
3551b80…
|
noreply
|
230 |
|
|
3551b80…
|
noreply
|
231 |
### cli_adapter |
|
3551b80…
|
noreply
|
232 |
|
|
3551b80…
|
noreply
|
233 |
**Description:** Push artifacts to external tools via their CLIs. |
|
3551b80…
|
noreply
|
234 |
|
|
3551b80…
|
noreply
|
235 |
Converts artifacts into CLI commands for external project management tools. Supported tools: |
|
3551b80…
|
noreply
|
236 |
|
|
3551b80…
|
noreply
|
237 |
| Tool | CLI | Example Command | |
|
3551b80…
|
noreply
|
238 |
|---|---|---| |
|
3551b80…
|
noreply
|
239 |
| `github` | `gh` | `gh issue create --title "..." --body "..." --label "..."` | |
|
3551b80…
|
noreply
|
240 |
| `jira` | `jira` | `jira issue create --summary "..." --description "..."` | |
|
3551b80…
|
noreply
|
241 |
| `linear` | `linear` | `linear issue create --title "..." --description "..."` | |
|
3551b80…
|
noreply
|
242 |
|
|
3551b80…
|
noreply
|
243 |
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. |
|
3551b80…
|
noreply
|
244 |
|
|
3551b80…
|
noreply
|
245 |
**Artifact type:** `cli_commands` | **Format:** json |
|
3551b80…
|
noreply
|
246 |
|
|
3551b80…
|
noreply
|
247 |
### notes_export |
|
3551b80…
|
noreply
|
248 |
|
|
3551b80…
|
noreply
|
249 |
**Description:** Export knowledge graph as structured notes (Obsidian, Notion). |
|
3551b80…
|
noreply
|
250 |
|
|
3551b80…
|
noreply
|
251 |
Exports the entire knowledge graph as a collection of markdown files optimized for a specific note-taking platform. Accepts a `format` parameter: |
|
3551b80…
|
noreply
|
252 |
|
|
3551b80…
|
noreply
|
253 |
**Obsidian format** creates: |
|
3551b80…
|
noreply
|
254 |
|
|
3551b80…
|
noreply
|
255 |
- One `.md` file per entity with YAML frontmatter, tags, and `[[wiki-links]]` |
|
3551b80…
|
noreply
|
256 |
- An `_Index.md` Map of Content grouping entities by type |
|
3551b80…
|
noreply
|
257 |
- Tag pages for each entity type |
|
3551b80…
|
noreply
|
258 |
- Artifact notes for any generated artifacts |
|
3551b80…
|
noreply
|
259 |
|
|
3551b80…
|
noreply
|
260 |
**Notion format** creates: |
|
3551b80…
|
noreply
|
261 |
|
|
3551b80…
|
noreply
|
262 |
- One `.md` file per entity with Notion-style callout blocks and relationship tables |
|
3551b80…
|
noreply
|
263 |
- An `entities_database.csv` for bulk import into a Notion database |
|
3551b80…
|
noreply
|
264 |
- An `Overview.md` page with stats and entity listings |
|
3551b80…
|
noreply
|
265 |
- Artifact pages |
|
3551b80…
|
noreply
|
266 |
|
|
3551b80…
|
noreply
|
267 |
**Artifact type:** `notes_export` | **Format:** markdown |
|
3551b80…
|
noreply
|
268 |
|
|
3551b80…
|
noreply
|
269 |
### wiki_generator |
|
3551b80…
|
noreply
|
270 |
|
|
3551b80…
|
noreply
|
271 |
**Description:** Generate a GitHub wiki from knowledge graph and artifacts. |
|
3551b80…
|
noreply
|
272 |
|
|
3551b80…
|
noreply
|
273 |
Generates a complete GitHub wiki structure as a dictionary of page names to markdown content. Creates: |
|
3551b80…
|
noreply
|
274 |
|
|
3551b80…
|
noreply
|
275 |
- **Home** page with entity type counts and links |
|
3551b80…
|
noreply
|
276 |
- **_Sidebar** navigation with entity types and artifacts |
|
3551b80…
|
noreply
|
277 |
- **Type index pages** with tables of entities per type |
|
3551b80…
|
noreply
|
278 |
- **Individual entity pages** with descriptions, outgoing/incoming relationships, and source occurrences |
|
3551b80…
|
noreply
|
279 |
- **Artifact pages** for any generated planning artifacts |
|
3551b80…
|
noreply
|
280 |
|
|
3551b80…
|
noreply
|
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. |
|
3551b80…
|
noreply
|
282 |
|
|
3551b80…
|
noreply
|
283 |
**Artifact type:** `wiki` | **Format:** markdown |
|
3551b80…
|
noreply
|
284 |
|
|
3551b80…
|
noreply
|
285 |
--- |
|
3551b80…
|
noreply
|
286 |
|
|
3551b80…
|
noreply
|
287 |
## CLI Usage |
|
3551b80…
|
noreply
|
288 |
|
|
3551b80…
|
noreply
|
289 |
### One-shot execution |
|
3551b80…
|
noreply
|
290 |
|
|
3551b80…
|
noreply
|
291 |
Run the agent with a request string. The agent selects and executes appropriate skills automatically. |
|
3551b80…
|
noreply
|
292 |
|
|
3551b80…
|
noreply
|
293 |
```bash |
|
3551b80…
|
noreply
|
294 |
# Generate a project plan |
|
3551b80…
|
noreply
|
295 |
planopticon agent "Create a project plan" --kb ./results |
|
3551b80…
|
noreply
|
296 |
|
|
3551b80…
|
noreply
|
297 |
# Generate a PRD |
|
3551b80…
|
noreply
|
298 |
planopticon agent "Write a PRD for the authentication system" --kb ./results |
|
3551b80…
|
noreply
|
299 |
|
|
3551b80…
|
noreply
|
300 |
# Break down into tasks |
|
3551b80…
|
noreply
|
301 |
planopticon agent "Break this into tasks and estimate effort" --kb ./results |
|
3551b80…
|
noreply
|
302 |
``` |
|
3551b80…
|
noreply
|
303 |
|
|
3551b80…
|
noreply
|
304 |
### Export artifacts to disk |
|
3551b80…
|
noreply
|
305 |
|
|
3551b80…
|
noreply
|
306 |
Use `--export` to write generated artifacts to a directory: |
|
3551b80…
|
noreply
|
307 |
|
|
3551b80…
|
noreply
|
308 |
```bash |
|
3551b80…
|
noreply
|
309 |
planopticon agent "Create a full project plan with tasks" --kb ./results --export ./output |
|
3551b80…
|
noreply
|
310 |
``` |
|
3551b80…
|
noreply
|
311 |
|
|
3551b80…
|
noreply
|
312 |
### Interactive mode |
|
3551b80…
|
noreply
|
313 |
|
|
3551b80…
|
noreply
|
314 |
Use `-I` for a multi-turn session where you can issue multiple requests: |
|
3551b80…
|
noreply
|
315 |
|
|
3551b80…
|
noreply
|
316 |
```bash |
|
3551b80…
|
noreply
|
317 |
planopticon agent -I --kb ./results |
|
3551b80…
|
noreply
|
318 |
``` |
|
3551b80…
|
noreply
|
319 |
|
|
3551b80…
|
noreply
|
320 |
In interactive mode, the agent supports: |
|
3551b80…
|
noreply
|
321 |
|
|
3551b80…
|
noreply
|
322 |
- Free-text requests (executed via LLM skill selection) |
|
3551b80…
|
noreply
|
323 |
- `/plan` -- shortcut to generate a project plan |
|
3551b80…
|
noreply
|
324 |
- `/skills` -- list available skills |
|
3551b80…
|
noreply
|
325 |
- `quit`, `exit`, `q` -- end the session |
|
3551b80…
|
noreply
|
326 |
|
|
3551b80…
|
noreply
|
327 |
### Provider and model options |
|
3551b80…
|
noreply
|
328 |
|
|
3551b80…
|
noreply
|
329 |
```bash |
|
3551b80…
|
noreply
|
330 |
# Use a specific provider |
|
3551b80…
|
noreply
|
331 |
planopticon agent "Create a roadmap" --kb ./results -p anthropic |
|
3551b80…
|
noreply
|
332 |
|
|
3551b80…
|
noreply
|
333 |
# Use a specific model |
|
3551b80…
|
noreply
|
334 |
planopticon agent "Generate a PRD" --kb ./results --chat-model gpt-4o |
|
3551b80…
|
noreply
|
335 |
``` |
|
3551b80…
|
noreply
|
336 |
|
|
3551b80…
|
noreply
|
337 |
### Auto-discovery |
|
3551b80…
|
noreply
|
338 |
|
|
3551b80…
|
noreply
|
339 |
If `--kb` is not specified, the agent uses `KBContext.auto_discover()` to find knowledge graphs in the workspace. |
|
3551b80…
|
noreply
|
340 |
|
|
3551b80…
|
noreply
|
341 |
--- |
|
3551b80…
|
noreply
|
342 |
|
|
3551b80…
|
noreply
|
343 |
## Using Skills from the Companion REPL |
|
3551b80…
|
noreply
|
344 |
|
|
3551b80…
|
noreply
|
345 |
The Companion REPL provides direct access to agent skills through slash commands. See the [Companion guide](companion.md) for full details. |
|
3551b80…
|
noreply
|
346 |
|
|
3551b80…
|
noreply
|
347 |
| Companion Command | Skill Executed | |
|
3551b80…
|
noreply
|
348 |
|---|---| |
|
3551b80…
|
noreply
|
349 |
| `/plan` | `project_plan` | |
|
3551b80…
|
noreply
|
350 |
| `/prd` | `prd` | |
|
3551b80…
|
noreply
|
351 |
| `/tasks` | `task_breakdown` | |
|
3551b80…
|
noreply
|
352 |
| `/run SKILL_NAME` | Any registered skill by name | |
|
3551b80…
|
noreply
|
353 |
|
|
3551b80…
|
noreply
|
354 |
When executed from the Companion, skills use the same `AgentContext` that powers the chat mode. This means: |
|
3551b80…
|
noreply
|
355 |
|
|
3551b80…
|
noreply
|
356 |
- The knowledge graph loaded at startup is automatically available |
|
3551b80…
|
noreply
|
357 |
- The active LLM provider (set via `/provider` or `/model`) is used for generation |
|
3551b80…
|
noreply
|
358 |
- Generated artifacts accumulate across the session, enabling chaining |
|
3551b80…
|
noreply
|
359 |
|
|
3551b80…
|
noreply
|
360 |
--- |
|
3551b80…
|
noreply
|
361 |
|
|
3551b80…
|
noreply
|
362 |
## Example Workflows |
|
3551b80…
|
noreply
|
363 |
|
|
3551b80…
|
noreply
|
364 |
### From video to project plan |
|
3551b80…
|
noreply
|
365 |
|
|
3551b80…
|
noreply
|
366 |
```bash |
|
3551b80…
|
noreply
|
367 |
# 1. Analyze a video |
|
3551b80…
|
noreply
|
368 |
planopticon analyze -i sprint-review.mp4 -o results/ |
|
3551b80…
|
noreply
|
369 |
|
|
3551b80…
|
noreply
|
370 |
# 2. Launch the agent with the results |
|
3551b80…
|
noreply
|
371 |
planopticon agent "Create a comprehensive project plan with tasks and a roadmap" \ |
|
3551b80…
|
noreply
|
372 |
--kb results/ --export plan/ |
|
3551b80…
|
noreply
|
373 |
|
|
3551b80…
|
noreply
|
374 |
# 3. Review the generated artifacts |
|
3551b80…
|
noreply
|
375 |
ls plan/ |
|
3551b80…
|
noreply
|
376 |
# project_plan.md roadmap.md tasks.json manifest.json |
|
3551b80…
|
noreply
|
377 |
``` |
|
3551b80…
|
noreply
|
378 |
|
|
3551b80…
|
noreply
|
379 |
### Interactive planning session |
|
3551b80…
|
noreply
|
380 |
|
|
3551b80…
|
noreply
|
381 |
```bash |
|
3551b80…
|
noreply
|
382 |
$ planopticon companion --kb ./results |
|
3551b80…
|
noreply
|
383 |
|
|
3551b80…
|
noreply
|
384 |
planopticon> /status |
|
3551b80…
|
noreply
|
385 |
Workspace status: |
|
3551b80…
|
noreply
|
386 |
KG: knowledge_graph.db (58 entities, 124 relationships) |
|
3551b80…
|
noreply
|
387 |
... |
|
3551b80…
|
noreply
|
388 |
|
|
3551b80…
|
noreply
|
389 |
planopticon> What are the main goals discussed? |
|
3551b80…
|
noreply
|
390 |
Based on the knowledge graph, the main goals are... |
|
3551b80…
|
noreply
|
391 |
|
|
3551b80…
|
noreply
|
392 |
planopticon> /plan |
|
3551b80…
|
noreply
|
393 |
--- Project Plan (project_plan) --- |
|
3551b80…
|
noreply
|
394 |
... |
|
3551b80…
|
noreply
|
395 |
|
|
3551b80…
|
noreply
|
396 |
planopticon> /tasks |
|
3551b80…
|
noreply
|
397 |
--- Task Breakdown (task_list) --- |
|
3551b80…
|
noreply
|
398 |
... |
|
3551b80…
|
noreply
|
399 |
|
|
3551b80…
|
noreply
|
400 |
planopticon> /run github_issues |
|
3551b80…
|
noreply
|
401 |
--- GitHub Issues (issues) --- |
|
3551b80…
|
noreply
|
402 |
[ |
|
3551b80…
|
noreply
|
403 |
{"title": "Set up authentication service", ...}, |
|
3551b80…
|
noreply
|
404 |
... |
|
3551b80…
|
noreply
|
405 |
] |
|
3551b80…
|
noreply
|
406 |
|
|
3551b80…
|
noreply
|
407 |
planopticon> /run artifact_export |
|
3551b80…
|
noreply
|
408 |
--- Export Manifest (export_manifest) --- |
|
3551b80…
|
noreply
|
409 |
{ |
|
3551b80…
|
noreply
|
410 |
"artifact_count": 3, |
|
3551b80…
|
noreply
|
411 |
"output_dir": "plan", |
|
3551b80…
|
noreply
|
412 |
"files": [...] |
|
3551b80…
|
noreply
|
413 |
} |
|
3551b80…
|
noreply
|
414 |
``` |
|
3551b80…
|
noreply
|
415 |
|
|
3551b80…
|
noreply
|
416 |
### Skill chaining |
|
3551b80…
|
noreply
|
417 |
|
|
3551b80…
|
noreply
|
418 |
Skills that produce artifacts make them available to subsequent skills automatically: |
|
3551b80…
|
noreply
|
419 |
|
|
3551b80…
|
noreply
|
420 |
1. `/tasks` generates a `task_list` artifact |
|
3551b80…
|
noreply
|
421 |
2. `/run github_issues` detects the existing `task_list` artifact and converts its tasks into GitHub issues |
|
3551b80…
|
noreply
|
422 |
3. `/run cli_adapter` takes the most recent artifact and generates `gh issue create` commands |
|
3551b80…
|
noreply
|
423 |
4. `/run artifact_export` writes all accumulated artifacts to disk with a manifest |
|
3551b80…
|
noreply
|
424 |
|
|
3551b80…
|
noreply
|
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. |