Skip to content

Commit a9b9ec4

Browse files
author
catlog22
committed
feat: add license files for JavaScript assets and implement DocItem component
- Added LICENSE.txt file for JavaScript assets in the build directory, including licenses for NProgress and React libraries. - Introduced a new runtime JavaScript file for handling module loading. - Created a new DocItem component to manage document rendering and metadata handling in the Docusaurus theme. - Implemented tests for the docs proxy server to ensure proper routing to the configured docsPort.
1 parent f9188eb commit a9b9ec4

91 files changed

Lines changed: 780 additions & 217 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

.codex/agents/cli-explore-agent.md

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -184,3 +184,33 @@ Brief summary:
184184
3. Guess field names - ALWAYS copy from schema
185185
4. Assume structure - ALWAYS verify against schema
186186
5. Omit required fields
187+
188+
---
189+
190+
## Post-Exploration: Exploration Notes (Generated by Orchestrator)
191+
192+
**Note**: This section is executed by the orchestrator (workflow-lite-plan) after all cli-explore-agents complete, NOT by this agent.
193+
194+
**Trigger**: After all exploration-{angle}.json files are generated
195+
196+
**Output Files**:
197+
- `exploration-notes.md` - Full version (consumed by Plan phase)
198+
- `exploration-notes-refined.md` - Refined version (consumed by Execute phase, generated after Plan completes)
199+
200+
**Full Version Structure (6 Sections)**:
201+
1. **Part 1: Multi-Angle Exploration Summary** - Key findings from each angle
202+
2. **Part 2: File Deep-Dive Summary** - Core files with relevance ≥ 0.7 (code snippets, line numbers, references)
203+
3. **Part 3: Architecture Reasoning Chains** - Reasoning process for key decisions (problem → reasoning → conclusion)
204+
4. **Part 4: Potential Risks and Mitigations** - Identified risks and mitigation strategies
205+
5. **Part 5: Clarification Questions Summary** - Aggregated clarification_needs from all angles
206+
6. **Part 6: Execution Recommendations Checklist** - Task checklist grouped by priority (P0/P1/P2)
207+
208+
**Refined Version Structure** (generated after Plan completes):
209+
- Execution-relevant file index (only files related to plan.json tasks)
210+
- Task-relevant exploration context (relevant findings per task)
211+
- Condensed code reference (only plan-related files)
212+
- Execution notes (constraints, integration points, dependencies)
213+
214+
**Consumption Pattern**:
215+
- Plan phase: Fully consumes `exploration-notes.md`
216+
- Execute phase: Consumes `exploration-notes-refined.md`, reduced noise, improved efficiency

.codex/skills/workflow-lite-plan/phases/01-lite-plan.md

Lines changed: 231 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ Intelligent lightweight planning command with dynamic workflow adaptation based
2626
|----------|-------------|
2727
| `exploration-{angle}.json` | Per-angle exploration results (1-4 files based on complexity) |
2828
| `explorations-manifest.json` | Index of all exploration files |
29+
| `exploration-notes.md` | Full exploration log (consumed by Plan phase, 6 sections) |
30+
| `exploration-notes-refined.md` | Refined exploration log (consumed by Execute phase, task-relevant only) |
2931
| `planning-context.md` | Evidence paths + synthesized understanding |
3032
| `plan.json` | Structured implementation plan (plan-json-schema.json) |
3133

@@ -340,6 +342,115 @@ Angles explored: ${explorationManifest.explorations.map(e => e.angle).join(', ')
340342
- ... (1-4 files based on complexity)
341343
- `${sessionFolder}/explorations-manifest.json`
342344

345+
**Generate Exploration Notes** (auto-generated after exploration completes):
346+
347+
```javascript
348+
// Step 1: Load all exploration JSON files
349+
const manifest = JSON.parse(Read(`${sessionFolder}/explorations-manifest.json`))
350+
const explorations = manifest.explorations.map(exp => ({
351+
angle: exp.angle,
352+
data: JSON.parse(Read(exp.path))
353+
}))
354+
355+
// Step 2: Extract core files (relevance ≥ 0.7)
356+
const coreFiles = []
357+
explorations.forEach(exp => {
358+
if (Array.isArray(exp.data.relevant_files)) {
359+
exp.data.relevant_files.forEach(f => {
360+
if (typeof f === 'object' && f.relevance >= 0.7) {
361+
coreFiles.push({ path: f.path, relevance: f.relevance, rationale: f.rationale, angle: exp.angle })
362+
}
363+
})
364+
}
365+
})
366+
const uniqueCoreFiles = deduplicateByPath(coreFiles.sort((a, b) => b.relevance - a.relevance))
367+
368+
// Step 3: Build exploration notes Markdown (6 sections)
369+
const explorationLog = `# Exploration Notes: ${task_description.slice(0, 60)}
370+
371+
**Generated**: ${getUtc8ISOString()}
372+
**Task**: ${task_description}
373+
**Complexity**: ${complexity}
374+
**Exploration Angles**: ${explorations.map(e => e.angle).join(', ')}
375+
376+
---
377+
378+
## Part 1: Multi-Angle Exploration Summary
379+
380+
${explorations.map(exp => `### Angle: ${exp.angle}
381+
382+
**Key Files** (priority sorted):
383+
${formatFileList(exp.data.relevant_files)}
384+
385+
**Code Patterns**: ${exp.data.patterns}
386+
387+
**Integration Points**: ${exp.data.integration_points}
388+
389+
**Dependencies**: ${exp.data.dependencies}
390+
391+
**Constraints**: ${exp.data.constraints}
392+
`).join('\n---\n')}
393+
394+
---
395+
396+
## Part 2: File Deep-Dive Summary
397+
398+
${uniqueCoreFiles.slice(0, 10).map(file => {
399+
const content = Read(file.path)
400+
const refs = Bash(\`rg "from ['\"].*${path.basename(file.path, path.extname(file.path))}['\"]" --type ts -n | head -10\`)
401+
return formatFileDeepDive(file, content, refs)
402+
}).join('\n---\n')}
403+
404+
---
405+
406+
## Part 3: Architecture Reasoning Chains
407+
408+
${buildReasoningChains(explorations, task_description)}
409+
410+
---
411+
412+
## Part 4: Potential Risks and Mitigations
413+
414+
${buildRiskMitigations(explorations, uniqueCoreFiles)}
415+
416+
---
417+
418+
## Part 5: Clarification Questions Summary
419+
420+
${aggregateClarifications(explorations)}
421+
422+
---
423+
424+
## Part 6: Execution Recommendations Checklist
425+
426+
${generateExecutionChecklist(task_description, explorations, uniqueCoreFiles)}
427+
428+
---
429+
430+
## Appendix: Key Code Location Index
431+
432+
| Component | File Path | Key Lines | Purpose |
433+
|-----------|-----------|-----------|---------|
434+
${uniqueCoreFiles.slice(0, 15).map(f => `| ${path.basename(f.path)} | ${f.path} | - | ${f.rationale} |`).join('\n')}
435+
`
436+
437+
// Step 4: Write initial exploration notes
438+
Write(`${sessionFolder}/exploration-notes.md`, explorationLog)
439+
440+
console.log(`
441+
## Exploration Notes Generated
442+
443+
File: ${sessionFolder}/exploration-notes.md
444+
Core files: ${uniqueCoreFiles.length}
445+
Angles: ${explorations.map(e => e.angle).join(', ')}
446+
447+
This log will be fully consumed by planning phase, then refined for execution.
448+
`)
449+
```
450+
451+
**Output (new)**:
452+
- `${sessionFolder}/exploration-notes.md` (full version, consumed by Plan phase)
453+
343454
---
344455
345456
### Phase 2: Clarification (Optional, Multi-Round)
@@ -557,6 +668,116 @@ close_agent({ id: planningAgentId })
557668
558669
**Output**: `${sessionFolder}/plan.json`
559670
671+
**Refine Exploration Notes** (auto-executed after Plan completes):
672+
673+
**Purpose**: Refine exploration-notes.md based on actual tasks in plan.json, keeping only execution-relevant content
674+
675+
```javascript
676+
// Step 1: Load plan and exploration notes
677+
const plan = JSON.parse(Read(`${sessionFolder}/plan.json`))
678+
const explorationLog = Read(`${sessionFolder}/exploration-notes.md`)
679+
680+
// Step 2: Extract files and modules from plan
681+
const planFiles = new Set()
682+
const planScopes = new Set()
683+
plan.tasks.forEach(task => {
684+
if (task.scope) planScopes.add(task.scope)
685+
if (task.modification_points) {
686+
task.modification_points.forEach(mp => planFiles.add(mp.file))
687+
}
688+
if (task.reference?.files) {
689+
task.reference.files.forEach(f => planFiles.add(f))
690+
}
691+
})
692+
693+
// Step 3: Build refined exploration notes
694+
const refinedLog = `# Exploration Notes (Refined): ${task_description.slice(0, 60)}
695+
696+
**Generated**: ${getUtc8ISOString()}
697+
**Task**: ${task_description}
698+
**Plan Tasks**: ${plan.tasks.length}
699+
**Refined For**: Execution phase consumption
700+
701+
---
702+
703+
## Execution-Relevant File Index
704+
705+
The following files are directly related to plan.json tasks, prioritize these during execution:
706+
707+
${Array.from(planFiles).map(f => `- \`${f}\``).join('\n')}
708+
709+
---
710+
711+
## Part 1: Task-Relevant Exploration Context
712+
713+
${plan.tasks.map(task => {
714+
// Extract content relevant to this task from original exploration notes
715+
return `### Task: ${task.title}
716+
717+
**Scope**: \`${task.scope}\`
718+
**Files**: ${task.modification_points?.map(mp => mp.file).join(', ') || 'N/A'}
719+
720+
**Relevant Exploration Findings**:
721+
${extractRelevantExploration(explorationLog, task)}
722+
723+
**Reference Patterns**:
724+
${task.reference?.pattern || 'See exploration notes Part 1 patterns'}
725+
726+
**Risk Notes**:
727+
${extractRelevantRisks(explorationLog, task)}
728+
`
729+
}).join('\n---\n')}
730+
731+
---
732+
733+
## Part 2: Condensed Code Reference
734+
735+
${Array.from(planFiles).slice(0, 8).map(filePath => {
736+
// Extract file deep-dive from original exploration notes Part 2
737+
return extractFileDeepDive(explorationLog, filePath) || `### ${filePath}\n\n(See original exploration notes for details)`
738+
}).join('\n---\n')}
739+
740+
---
741+
742+
## Part 3: Execution Notes
743+
744+
### Key Constraints (from exploration)
745+
${extractConstraints(explorationLog)}
746+
747+
### Integration Points (plan-task related)
748+
${extractIntegrationPoints(explorationLog, planFiles)}
749+
750+
### Dependencies
751+
${extractDependencies(explorationLog, planFiles)}
752+
753+
---
754+
755+
## Appendix: Full Exploration Notes Location
756+
757+
Original full exploration notes: \`${sessionFolder}/exploration-notes.md\`
758+
759+
For additional context, refer to:
760+
- Part 3: Architecture Reasoning Chains
761+
- Part 4: Potential Risks and Mitigations
762+
- Part 5: Clarification Questions Summary
763+
`
764+
765+
// Step 4: Write refined exploration notes
766+
Write(`${sessionFolder}/exploration-notes-refined.md`, refinedLog)
767+
768+
// Step 5: Update session artifacts
769+
console.log(`
770+
## Exploration Notes Refined
771+
772+
Original: ${sessionFolder}/exploration-notes.md (full version, for Plan reference)
773+
Refined: ${sessionFolder}/exploration-notes-refined.md (condensed, for Execute consumption)
774+
775+
Refined for ${plan.tasks.length} tasks, ${planFiles.size} files
776+
`)
777+
```
778+
779+
**Output (new)**: `${sessionFolder}/exploration-notes-refined.md`
780+
560781
---
561782
562783
### Phase 4: Task Confirmation & Execution Selection
@@ -683,6 +904,8 @@ executionContext = {
683904
path: exp.path
684905
})),
685906
explorations_manifest: `${sessionFolder}/explorations-manifest.json`,
907+
exploration_log: `${sessionFolder}/exploration-notes.md`, // Full version (Plan consumption)
908+
exploration_log_refined: `${sessionFolder}/exploration-notes-refined.md`, // Refined version (Execute consumption)
686909
plan: `${sessionFolder}/plan.json`
687910
}
688911
}
@@ -699,12 +922,14 @@ executionContext = {
699922
700923
```
701924
.workflow/.lite-plan/{task-slug}-{YYYY-MM-DD}/
702-
├── exploration-{angle1}.json # Exploration angle 1
703-
├── exploration-{angle2}.json # Exploration angle 2
704-
├── exploration-{angle3}.json # Exploration angle 3 (if applicable)
705-
├── exploration-{angle4}.json # Exploration angle 4 (if applicable)
706-
├── explorations-manifest.json # Exploration index
707-
└── plan.json # Implementation plan
925+
├── exploration-{angle1}.json # Exploration angle 1
926+
├── exploration-{angle2}.json # Exploration angle 2
927+
├── exploration-{angle3}.json # Exploration angle 3 (if applicable)
928+
├── exploration-{angle4}.json # Exploration angle 4 (if applicable)
929+
├── explorations-manifest.json # Exploration index
930+
├── exploration-notes.md # Full exploration notes (Plan phase consumption)
931+
├── exploration-notes-refined.md # Refined exploration notes (Execute phase consumption)
932+
└── plan.json # Implementation plan
708933
```
709934
710935
**Example**:

.codex/skills/workflow-lite-plan/phases/04-lite-execute.md

Lines changed: 51 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -381,6 +381,21 @@ ${t.verification?.success_metrics?.length > 0 ? `\n**Success metrics**: ${t.veri
381381
382382
// Context (reference only)
383383
const context = []
384+
385+
// Priority: reference refined exploration notes (Execute phase specific)
386+
if (executionContext?.session?.artifacts?.exploration_log_refined) {
387+
context.push(`### Exploration Notes (Refined)
388+
**Read first**: ${executionContext.session.artifacts.exploration_log_refined}
389+
390+
This refined notes contains only execution-relevant context:
391+
- Execution-relevant file index (files directly related to plan tasks)
392+
- Task-relevant exploration context (findings, patterns, risks per task)
393+
- Condensed code reference (code snippets with line numbers)
394+
- Execution notes (constraints, integration points, dependencies)
395+
396+
**IMPORTANT**: Use this refined notes to avoid re-exploring files. DO NOT re-read files already analyzed in the notes unless verifying specific implementation details.`)
397+
}
398+
384399
if (previousExecutionResults.length > 0) {
385400
context.push(`### Previous Work\n${previousExecutionResults.map(r => `- ${r.tasksSummary}: ${r.status}`).join('\n')}`)
386401
}
@@ -411,12 +426,38 @@ When to use:
411426
- or `executionMethod = "Auto" AND complexity = "Low"` (global fallback)
412427
413428
```javascript
414-
Task(
415-
subagent_type="code-developer",
416-
run_in_background=false,
417-
description=batch.taskSummary,
418-
prompt=buildExecutionPrompt(batch)
419-
)
429+
// Step 1: Create execution agent with mandatory context reading
430+
const executionAgentId = spawn_agent({
431+
message: `
432+
## TASK ASSIGNMENT
433+
434+
### MANDATORY FIRST STEPS (Agent Execute)
435+
1. **Read role definition**: ~/.codex/agents/code-developer.md (MUST read first)
436+
2. Read: .workflow/project-tech.json
437+
3. Read: .workflow/project-guidelines.json
438+
4. **Read refined exploration log**: ${executionContext?.session?.artifacts?.exploration_log_refined || 'N/A'}
439+
440+
**CRITICAL**: Step 4 contains execution-relevant context including:
441+
- Task-relevant code patterns and integration points
442+
- Condensed code reference (with line numbers)
443+
- Execution constraints and risk notes
444+
445+
Use the notes to avoid re-exploring files - the analysis is already done.
446+
447+
---
448+
449+
${buildExecutionPrompt(batch)}
450+
`
451+
})
452+
453+
// Step 2: Wait for execution completion
454+
const execResult = wait({
455+
ids: [executionAgentId],
456+
timeout_ms: 600000 // 10 minutes
457+
})
458+
459+
// Step 3: Close execution agent
460+
close_agent({ id: executionAgentId })
420461
```
421462
422463
**Result Collection**: After completion, collect result following `executionResult` structure (see Data Structures section)
@@ -683,14 +724,17 @@ Passed from planning phase via global variable:
683724
artifacts: {
684725
explorations: [{angle, path}], // exploration-{angle}.json paths
685726
explorations_manifest: string, // explorations-manifest.json path
727+
exploration_log: string, // exploration-notes.md (full version, Plan consumption)
728+
exploration_log_refined: string, // exploration-notes-refined.md (refined version, Execute consumption)
686729
plan: string // plan.json path (always present)
687730
}
688731
}
689732
}
690733
```
691734
692735
**Artifact Usage**:
693-
- Artifact files contain detailed planning context
736+
- **exploration_log**: Full exploration notes, for Plan phase reference, contains 6 sections
737+
- **exploration_log_refined**: Refined exploration notes, for Execute phase consumption, task-relevant content only
694738
- Pass artifact paths to CLI tools and agents for enhanced context
695739
- See execution options above for usage examples
696740

0 commit comments

Comments
 (0)