chore: push all design docs, V2 plan specs, and current working state
Includes AirPlan design documents, AircOding-alpha1-plan, AirPlanV2, AirPlan-ParaV2, AirPlan-Para V1 reference docs, and all working code changes across packages. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
AirCoding
262
AirPlan/docs/spec/AirPlan-ParaV2/init_project_airplan.ps1
Executable file
262
AirPlan/docs/spec/AirPlan-ParaV2/init_project_airplan.ps1
Executable file
@@ -0,0 +1,262 @@
|
||||
param(
|
||||
[string]$ProjectRoot = ".",
|
||||
[switch]$Force
|
||||
)
|
||||
|
||||
$ErrorActionPreference = "Stop"
|
||||
|
||||
$resolvedProjectRoot = (Resolve-Path $ProjectRoot).Path
|
||||
$airPlanRoot = Join-Path $resolvedProjectRoot "AirPlan"
|
||||
|
||||
function Ensure-Directory {
|
||||
param([Parameter(Mandatory = $true)][string]$Path)
|
||||
New-Item -ItemType Directory -Path $Path -Force | Out-Null
|
||||
}
|
||||
|
||||
function Write-TextFile {
|
||||
param(
|
||||
[Parameter(Mandatory = $true)][string]$Path,
|
||||
[Parameter(Mandatory = $true)][string]$Content
|
||||
)
|
||||
|
||||
if ((Test-Path -LiteralPath $Path) -and (-not $Force)) {
|
||||
Write-Output ("skipped=" + $Path)
|
||||
return
|
||||
}
|
||||
|
||||
$parent = Split-Path -Parent $Path
|
||||
if ($parent) {
|
||||
Ensure-Directory -Path $parent
|
||||
}
|
||||
[System.IO.File]::WriteAllText($Path, $Content.TrimStart("`n") + "`n", [System.Text.UTF8Encoding]::new($false))
|
||||
Write-Output ("written=" + $Path)
|
||||
}
|
||||
|
||||
$rootAgents = @'
|
||||
# AGENTS.md
|
||||
|
||||
- Canonical workflow context for this repository lives in `AirPlan/AGENTS.md`.
|
||||
- Always load `AirPlan/AGENTS.md` first for project instructions, workflow rules, plan/todo state, ADR/C4 context, and current Air sync blocks.
|
||||
- Treat `AirPlan/plan.md`, `AirPlan/todo.md`, and `AirPlan/docs/` as the authoritative workflow documents.
|
||||
- Treat `AirPlan/state/` as the authoritative plugin and runtime state root.
|
||||
- This root file is only a bootstrap shim; keep real workflow context maintained inside `AirPlan/AGENTS.md`.
|
||||
'@
|
||||
|
||||
$projectAgents = @'
|
||||
# AGENTS.md
|
||||
|
||||
## Workflow Root
|
||||
|
||||
- This project uses `AirPlan/` as the workflow root.
|
||||
- Keep planning, execution state, ADR, C4, validation, debug, and plugin runtime data under `AirPlan/`.
|
||||
- The repo-root `AGENTS.md` only bootstraps into this file.
|
||||
|
||||
<!-- AIRARC:BEGIN -->
|
||||
## AirArc Workflow
|
||||
|
||||
1. Use `AirPlan/AGENTS.md` as the canonical project context entry point.
|
||||
2. Load and maintain:
|
||||
- `AirPlan/docs/analysis/requirements.md`
|
||||
- `AirPlan/docs/architecture/solution-architecture.md`
|
||||
- `AirPlan/docs/architecture/c4/module.md`
|
||||
- `AirPlan/docs/architecture/adr/`
|
||||
3. Produce or refine `AirPlan/plan.md` and `AirPlan/todo.md`.
|
||||
4. Keep plans optimized for lower-cost follow-up sessions, including scope, validation, file targets, and parallelization boundaries.
|
||||
<!-- AIRARC:END -->
|
||||
|
||||
<!-- AIRENG:BEGIN -->
|
||||
## AirEng Workflow
|
||||
|
||||
1. Use `/aireng` as the scheduler for confirmed execution.
|
||||
2. Prefer `AirPlan/state/airarc/reviews/execution-plan.json`, then `AirPlan/state/airarc/reviews/parallel-review.json`, before falling back to local `AirPlan/todo.md`.
|
||||
3. Dispatch isolated `/airdo` subagents with bounded concurrency.
|
||||
4. Keep `AirPlan/todo.md`, `AirPlan/plan.md`, `AirPlan/AGENTS.md`, ADR, and C4 docs synchronized during dispatch and merge.
|
||||
5. AirEng owns global debug, XDB, repair, and document convergence.
|
||||
<!-- AIRENG:END -->
|
||||
|
||||
<!-- AIRDO:BEGIN -->
|
||||
## AirDo Workflow
|
||||
|
||||
1. Use `/airdo` for one narrow task slice from `AirPlan/todo.md`.
|
||||
2. Before editing, load:
|
||||
- `AirPlan/AGENTS.md`
|
||||
- `AirPlan/docs/architecture/adr/`
|
||||
- `AirPlan/docs/architecture/c4/module.md`
|
||||
- `AirPlan/plan.md`
|
||||
- `AirPlan/todo.md`
|
||||
3. Keep task-local progress resumable in `AirPlan/state/airdo/`.
|
||||
4. When AirEng owns orchestration, return shared document changes through `documentUpdates`.
|
||||
5. Route GUI work through AirXDB, debugging through AirDbg, network evidence through AirNDB, and static analysis through AirSDB when needed.
|
||||
<!-- AIRDO:END -->
|
||||
'@
|
||||
|
||||
$planMd = @'
|
||||
# Implementation Plan
|
||||
|
||||
## Read First
|
||||
1. `AirPlan/AGENTS.md`
|
||||
2. `AirPlan/docs/analysis/requirements.md`
|
||||
3. `AirPlan/docs/architecture/solution-architecture.md`
|
||||
4. `AirPlan/docs/architecture/c4/module.md`
|
||||
5. `AirPlan/docs/architecture/adr/`
|
||||
6. `AirPlan/todo.md`
|
||||
|
||||
## Goal
|
||||
- Replace this section with the concrete product or project goal.
|
||||
|
||||
## Constraints
|
||||
- Record technical, organizational, legal, hardware, or platform constraints here.
|
||||
|
||||
## Phases
|
||||
- Add implementation phases once AirArc planning is complete.
|
||||
|
||||
## Validation Strategy
|
||||
- Record build, test, debug, GUI, network, and static-analysis validation commands here.
|
||||
'@
|
||||
|
||||
$todoMd = @'
|
||||
# TODO
|
||||
|
||||
Status values: TODO / DOING / DONE / BLOCKED
|
||||
|
||||
| ID | Status | Module | Task | Files/Dirs | Done When | Validation | Static Analysis | ADR/C4 Update |
|
||||
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
|
||||
| T-001 | TODO | Planning | Replace with the first confirmed execution task | `AirPlan/plan.md`, `AirPlan/docs/` | Acceptance criteria are explicit and testable | Record the exact validation command | Record the static-analysis plan or why it is not applicable | Record required ADR or C4 updates |
|
||||
|
||||
## Quality Gates
|
||||
- Run the validation command listed in `AirPlan/plan.md` before marking a task `DONE`.
|
||||
- Keep ADR and C4 docs synchronized whenever architecture, module boundaries, dependencies, or ownership change.
|
||||
- Record skipped validation, residual risk, and follow-up work explicitly.
|
||||
'@
|
||||
|
||||
$requirementsMd = @'
|
||||
# Requirements
|
||||
|
||||
## Product Intent
|
||||
- Replace with the user-visible outcome this repository should deliver.
|
||||
|
||||
## Functional Requirements
|
||||
- Replace with numbered or grouped functional requirements.
|
||||
|
||||
## Constraints
|
||||
- Replace with non-functional constraints, environmental limits, or safety rules.
|
||||
|
||||
## Acceptance Notes
|
||||
- Replace with the most important acceptance criteria and evidence rules.
|
||||
'@
|
||||
|
||||
$solutionArchitectureMd = @'
|
||||
# Solution Architecture
|
||||
|
||||
## Overview
|
||||
- Replace with the top-level architecture summary.
|
||||
|
||||
## Major Components
|
||||
- Replace with the main containers and their responsibilities.
|
||||
|
||||
## Data And Control Flow
|
||||
- Replace with the major interaction paths between components.
|
||||
|
||||
## Key Risks
|
||||
- Replace with the architecture risks, unknowns, and open decisions.
|
||||
'@
|
||||
|
||||
$c4ModuleMd = @'
|
||||
# C4 Module
|
||||
|
||||
## System Context
|
||||
- Replace with the project purpose and external actors or systems.
|
||||
|
||||
## Containers
|
||||
- Replace with the main runtime or repository containers.
|
||||
|
||||
## Modules
|
||||
|
||||
| Module | Responsibility | Public Interfaces | Dependencies | Data Ownership | Quality Notes |
|
||||
| --- | --- | --- | --- | --- | --- |
|
||||
| `replace_me` | Replace with the first real module | Replace with interfaces | Replace with dependencies | Replace with owned data | Replace with testing or quality notes |
|
||||
'@
|
||||
|
||||
$adrMd = @'
|
||||
# ADR-0001: Use AirPlan As The Workflow Root
|
||||
|
||||
- Status: Accepted
|
||||
- Date: YYYY-MM-DD
|
||||
|
||||
## Context
|
||||
This project needs a durable workflow root for planning, execution state, architecture context, validation evidence, and resumable AI sessions.
|
||||
|
||||
## Decision
|
||||
Store project workflow artifacts under `AirPlan/`, use the repo-root `AGENTS.md` only as a bootstrap shim, and let `aireng` plus `airdo` maintain plan, todo, ADR, and C4 context there.
|
||||
|
||||
## Consequences
|
||||
- Planning and execution context stay resumable across sessions.
|
||||
- Global workflow docs live in one predictable location.
|
||||
- Plugin runtime state does not clutter the main project tree.
|
||||
'@
|
||||
|
||||
$debugLogMd = @'
|
||||
# Debug Log
|
||||
|
||||
- Add reproducible bug investigations, root-cause notes, and validation outcomes here.
|
||||
'@
|
||||
|
||||
$guiDebugLogMd = @'
|
||||
# GUI Debug Log
|
||||
|
||||
- Add screenshots, GUI observations, Midscene evidence, and visual acceptance notes here.
|
||||
'@
|
||||
|
||||
$networkLogMd = @'
|
||||
# AirNDB Log
|
||||
|
||||
- Add packet-capture commands, pcap paths, network observations, and conclusions here.
|
||||
'@
|
||||
|
||||
$staticAnalysisMd = @'
|
||||
# Static Analysis
|
||||
|
||||
- Add cppcheck or other static-analysis summaries, report paths, and residual risks here.
|
||||
'@
|
||||
|
||||
$validationReadme = @'
|
||||
# Validation Artifacts
|
||||
|
||||
- Save build logs, flash logs, test logs, screenshots, and validation summaries under this directory.
|
||||
'@
|
||||
|
||||
$artifactsReadme = @'
|
||||
# Artifact Output
|
||||
|
||||
- Save generated evidence files in this directory.
|
||||
'@
|
||||
|
||||
Ensure-Directory -Path $airPlanRoot
|
||||
Ensure-Directory -Path (Join-Path $airPlanRoot "docs\analysis")
|
||||
Ensure-Directory -Path (Join-Path $airPlanRoot "docs\architecture\adr")
|
||||
Ensure-Directory -Path (Join-Path $airPlanRoot "docs\architecture\c4")
|
||||
Ensure-Directory -Path (Join-Path $airPlanRoot "docs\debug\airxdb-artifacts")
|
||||
Ensure-Directory -Path (Join-Path $airPlanRoot "docs\network\airndb-captures")
|
||||
Ensure-Directory -Path (Join-Path $airPlanRoot "docs\validation\logs")
|
||||
Ensure-Directory -Path (Join-Path $airPlanRoot "state")
|
||||
|
||||
Write-TextFile -Path (Join-Path $resolvedProjectRoot "AGENTS.md") -Content $rootAgents
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "AGENTS.md") -Content $projectAgents
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "plan.md") -Content $planMd
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "todo.md") -Content $todoMd
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "docs\analysis\requirements.md") -Content $requirementsMd
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "docs\architecture\solution-architecture.md") -Content $solutionArchitectureMd
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "docs\architecture\c4\module.md") -Content $c4ModuleMd
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "docs\architecture\adr\ADR-0001-use-airplan-as-the-workflow-root.md") -Content $adrMd
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "docs\debug\debug-log.md") -Content $debugLogMd
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "docs\debug\gui-debug-log.md") -Content $guiDebugLogMd
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "docs\debug\airxdb-artifacts\README.md") -Content $artifactsReadme
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "docs\network\airndb-log.md") -Content $networkLogMd
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "docs\network\airndb-captures\README.md") -Content $artifactsReadme
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "docs\validation\README.md") -Content $validationReadme
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "docs\validation\logs\README.md") -Content $artifactsReadme
|
||||
Write-TextFile -Path (Join-Path $airPlanRoot "docs\staticanalysis.md") -Content $staticAnalysisMd
|
||||
|
||||
Write-Output ("airplan_project_init=completed")
|
||||
Write-Output ("project_root=" + $resolvedProjectRoot)
|
||||
Write-Output ("airplan_root=" + $airPlanRoot)
|
||||
Reference in New Issue
Block a user