init
Use when the user asks to set a project up for flowai for the first time — writes AGENTS.md and the documentation skeleton for a new or an existing codebase. Not for reconciling an existing AGENTS.md
SKILL.mdplugins/flowai/skills/init/SKILL.md
GitHubTask: Initialize Project Agent Documentation
Overview
Analyze the project, conduct an interview (for Greenfield projects), and
generate a single AGENTS.md file (root) with all project rules, a CLAUDE.md symlink
(for Claude Code compatibility), rules, and scaffolding.
Legacy three-file layouts (documents/AGENTS.md, scripts/AGENTS.md) are detected and collapsed into the single root file.
The agent uses template files from assets/ as reference and writes files directly.
Context
<context> The user wants to bootstrap an AI agent's understanding of the project. The agent needs to autonomously explore the codebase, recognize the technology stack, understand the directory structure, and infer key architectural patterns. - **Greenfield (New Projects)**: Requires interviewing the user, creating scaffolding (`documents/`, configs), and setting up rules. - **Brownfield (Existing Projects)**: Requires discovery, reverse-engineering architecture, and **collapsing legacy multi-file layouts** into the single root file.File Structure: init produces a single ./AGENTS.md file containing all sections:
- Project rules, metadata, vision, architecture, key decisions
- Documentation rules (task format, readability floor, chat output style, doc hierarchy). The SRS and SDS structures are NOT in AGENTS.md — they live in the pack-level templates
assets/SRS.template.mdandassets/SDS.template.md, which step 9 reads - Development commands (standard interface, detected commands)
- Planning rules, TDD flow, code documentation rules</context>
Rules & Constraints
<rules> 1. **No Hallucinations**: Only document tooling and architecture that is explicitly found in the codebase or provided by the user. 2. **Standard Format**: Generated files must follow the provided templates in `assets/`. 3. **Idempotency (Brownfield)**: If components already exist, show diffs and ask for per-file confirmation before applying changes, under the turn rule in constraint 8. 4. **Greenfield/Brownfield Detection**: The agent determines project type autonomously by analyzing output of the analysis script (file count, stack, file tree, presence of config files). Do NOT rely on an `is_new` flag from any script. 5. **Scripts are read-only**: Analysis scripts must NOT create, write, or modify any files. All file creation is the agent's responsibility. 6. **No rule copying**: Do NOT copy rules to IDE-specific rules directories. Rule management is outside init scope. 7. **Mandatory**: The agent MUST use a task management tool (e.g., todo write) to track the execution steps. 8. **Per-File Diff Confirmation**: For existing files, always show the diff to the user and ask for confirmation before applying. Never silently overwrite. **A diff is the proposed unified diff of that file, shown under the file's path** — a prose summary, a change list, an excerpt, or a grouped description of "what will change" is not a diff, and a bullet list covering several files is not one either. **Ask a separate yes/no per file; one grouped "May I apply these changes?" is not a per-file confirmation** and does not authorize any of the writes. The project's instruction file may prefer decision-level narration over diffs for ordinary work ("narrate upward, not in diffs"); that preference does not apply here — this step exists to let the user read the exact change to a file they own before it is replaced. **Asking ends the turn.** The write belongs to a LATER turn, after the user's answer has arrived. A question and the write it asks about cannot share a turn — that is not a confirmation, it is a narration of a decision already taken. "May I apply this?" followed by the edit tool in the same turn means the confirmation never happened. 9. **Preserve User Content**: In brownfield, extract and preserve user's existing instructions. Templates are fallbacks for greenfield only. 10. **Collapse, Don't Fragment**: In brownfield, if legacy `documents/AGENTS.md` or `scripts/AGENTS.md` exists, merge their unique content into the root `./AGENTS.md` and delete the originals after user confirmation. </rules>Instructions
<step_by_step>Initialize
- Use a task management tool (e.g., todo write) to create a plan based on these steps.
Analyze Project
- Run the analysis script to detect stack, inventory components, and verify setup. The script ships INSIDE this skill's directory, next to this SKILL.md (
<skill-dir>/scripts/generate_agents.ts, e.g..claude/skills/init/scripts/generate_agents.tsor.codex/skills/init/scripts/generate_agents.ts) — it is NOT in the project's ownscripts/. Run it from the project root by that path; a missingscripts/generate_agents.tsat the project root is the expected state, not a blocker:deno run --allow-read <skill-dir>/scripts/generate_agents.ts . - Read the JSON output. It wraps in
{ "ok": bool, "result": {...} }. Theresultfield contains: project metadata (is_new,stack,file_tree,readme_content), componentinventory, andverificationchecks. - Decision Point (agent judgment, NOT a script flag):
- Analyze file count, presence of source files, config files and existing documentation.
- If project appears empty or minimal (no source files, no meaningful configs) -> treat as Greenfield.
- If project has existing code, configs, or documentation -> treat as Brownfield.
- Run the analysis script to detect stack, inventory components, and verify setup. The script ships INSIDE this skill's directory, next to this SKILL.md (
Greenfield Workflow (Interview)
- Condition: Only if Greenfield.
- Action: Launch the
interviewersubagent (or conduct Q&A inline if subagent unavailable).Prompt: "You are helping initialize a new (Greenfield) project. Conduct a brief interview to gather:
- Project Name: Name?
- Vision Statement: What is the long-term goal and value?
- Target Audience: Who is this for?
- Problem Statement: What problem are we solving?
- Solution & Differentiators: How do we solve it and why is it better?
- Risks & Assumptions: What could go wrong?
- Tech Stack: Languages/Frameworks? (If not detected)
- Architecture: Patterns?
- Key Decisions: Tools/Methodologies?
- Deno Tooling: Do you want to build tooling around the project on Deno? (yes/no)
- Devcontainer: Would you like to set up a devcontainer for reproducible development environments? (yes/no)
Return a SINGLE JSON object: { "project_name": "...", "vision_statement": "...", "target_audience": "...", "problem_statement": "...", "solution_differentiators": "...", "risks_assumptions": "...", "stack": ["..."], "architecture": "...", "key_decisions": "...", "preferences": ["tdd", "strict-mode", ...], "use_deno_tooling": boolean, "use_devcontainer": boolean }"
Brownfield Workflow (Discovery & Extraction)
- Condition: Only if Brownfield.
- Action: Analyze the project to infer architecture and key decisions.
- Read key config files (
package.json,deno.json,README.md, etc.). - Infer:
- Architecture: (e.g., "React SPA", "Express API", "CLI Tool").
- Key Decisions: (e.g., "Tailwind for styling", "Jest for testing").
- Read key config files (
- Collapse legacy layout (if detected):
- Check
legacy_layout_detectedfrom the analyzer output. - If legacy layout found (
documents/AGENTS.mdand/orscripts/AGENTS.mdexist):- Read all existing files:
./AGENTS.md,./documents/AGENTS.md,./scripts/AGENTS.md. - Merge by section into the root file: documentation rules content →
## Documentation Rulessection, scripts content →## Development Commandssection, everything else stays in its existing root section. - Show the merged diff to the user and ask for confirmation.
- Overwrite
./AGENTS.mdwith the merged result. git rmthe two sub-files (documents/AGENTS.md,scripts/AGENTS.md) and theirCLAUDE.mdsymlinks (documents/CLAUDE.md,scripts/CLAUDE.md) if they exist.
- Read all existing files:
- If no legacy layout: proceed with normal brownfield discovery against
./AGENTS.md. - Important: The content from the user's existing files takes priority over template content. Templates are fallbacks only.
- Check
Component Inventory
- Use the
inventorysection from the analysis output (step 2) to check which components exist. - Report findings to user as a checklist.
- For Brownfield: ask "Create missing components? Update existing via diff? [create missing / update all / select]"
- Use the
Generate AGENTS.md File
Read the pack-level template at
assets/AGENTS.template.md(reference for./AGENTS.md, single file containing all sections).For Greenfield: Fill template with interview data. Replace
{{PLACEHOLDERS}}with actual values.For Brownfield:
./AGENTS.md: Use the template structure. Fill with data inferred from the project. Preserve user's custom PROJECT_RULES (content between---and the next##heading). If legacy layout was collapsed in step 4, the merged content is already prepared — use it.- Write step 4's inferences into
## Architectureand## Key Decisionsby name. An existing AGENTS.md whose sections are blank has nothing to preserve there — a blank section is the section you were asked to fill, not user content. Recording the same material in the SRS, the SDS or the init-context task file does not discharge this: those are different documents, and a reader of AGENTS.md never sees them.
Output: a single
./AGENTS.mdfile.- If file does not exist: create it, report to user.
- If file exists: show diff to user, ask for confirmation before writing.
Claude Code Compatibility (CLAUDE.md Symlink)
- Create a single relative symlink:
./CLAUDE.md->./AGENTS.md. - Symlink handling:
- If
CLAUDE.mddoes not exist: create the symlink, report to user. - If
CLAUDE.mdexists and is already a correct symlink toAGENTS.md: skip silently. - If
CLAUDE.mdexists as a regular file or wrong symlink: warn the user, show the current content/target, and ask for confirmation before replacing with the symlink.
- If
- Legacy cleanup: If legacy sub-directory
CLAUDE.mdsymlinks exist (documents/CLAUDE.md,scripts/CLAUDE.md), they should already be deleted during the legacy-collapse step (step 4). If they still exist at this point, delete them now.
- Create a single relative symlink:
OpenCode Compatibility Check
- The
inventorysection from the analysis output (step 2) includesopencode_json.existsandopencode_json.has_subdirectory_globs. - If
opencode_json.existsistrueand theinstructionsarray contains references todocuments/AGENTS.mdorscripts/AGENTS.md: propose removing only those stale entries. Do NOT add anAGENTS.mdreplacement entry — OpenCode auto-loads the root file.
- The
Generate Documentation
- Resolve documentation roles from the generated
AGENTS.md:SRS,SDS,tasks, andindex. If a role is missing, add it to AGENTS.md before generating docs. - Generate core documentation files at the resolved role paths:
SRS: Read the pack-level template atassets/SRS.template.mdand use its section and field structure verbatim (## 3. Functional Reqswith per-FR**Desc:**/**Rationale:**/**Scenario:**/**Acceptance:**/**Status:**fields —**Rationale:**is mandatory: write why each requirement exists, from the interview answers or the inferred context). Fill based on interview data (Greenfield) or inferred context (Brownfield). Skip if file exists and has more than 50 lines.SDS: Read the pack-level template atassets/SDS.template.mdand create the initial structure from it (## 3. Componentswith per-component**Purpose:**/**Interfaces:**/**Deps:**fields). Skip if file exists and has more than 50 lines.tasksdirectory:- For Brownfield: Create an init-context task using the role's layout with "Discovered Context" (file tree) and README summary.
- For Greenfield: Directory will be created on first use by planning/answer skills. No need to initialize.
- Note: Use LLM capabilities to generate high-quality, context-aware content from actual project data -- not empty placeholders.
- Resolve documentation roles from the generated
Configure Development Commands
- Read analysis output to get detected stack.
- Check Interview Data: If
use_deno_tooling: true, FORCE usage ofconfigure-deno-commands. - Skill Lookup: For each stack item, check if a specialized skill exists (e.g.,
Deno->configure-deno-commands). - If specialized skill exists: Read and follow its
SKILL.md. - If NO specialized skill:
- Detect the project's existing command runner (Makefile, package.json scripts, deno.json tasks, justfile, etc.).
- Ask user for preferred approach if none detected.
- Create standard command interface (
check,test,dev,prod) using the project's native command runner. For example, for Node.js projects add scripts topackage.json; for Make-based projects add targets toMakefile. Do NOT create ascripts/directory with wrapper scripts if the project's command runner can handle commands directly. - Only create helper scripts in a separate directory if the command logic is too complex for inline commands, and follow existing project conventions for script placement.
- Skip condition: If standard commands already exist in the project's command runner and user chose "create missing" -> skip.
- Verify: Run
checkcommand to ensure it works. - Record the commands in
./AGENTS.md: step 6 wrote the file before these commands existed, so its### Detected Commandsand### Command Scriptssections are still empty. Fill them now: under### Detected Commands, one line per standard command (check,test,dev,prod) with the exact invocation the project's runner uses (e.g.deno task check,make check,npm run check); under### Command Scripts, one line per helper script the step created with its path and purpose, or a one-line note that all commands are inline in the runner config. An empty section here is a missing step, not a placeholder to leave for later.
- Devcontainer Setup (Optional)
- For Greenfield: Check
use_devcontainerfrom interview data. - For Brownfield: Ask the user: "Would you like to set up a devcontainer for reproducible development environments?"
- If user declines: Skip this step entirely.
- If user agrees: Delegate to the
setup-ai-ide-devcontainerskill. Read and follow itsSKILL.md.
- Cleanup & Verify
- Remove temporary files:
project_info.json,interview_data.json(if created). - Re-run the analysis script (same skill-directory path as in step 2) to verify all components are in place:
deno run --allow-read <skill-dir>/scripts/generate_agents.ts . - Check the
verificationsection. Ifpassedis false (exit code 1), fix the issues before proceeding. - Additionally verify: development commands are configured, the
checkcommand runs successfully, and./AGENTS.mdlists those commands under### Detected Commands(step 10). - Verify single file: Confirm that only
./AGENTS.mdexists and no legacydocuments/AGENTS.mdorscripts/AGENTS.mdremain.
- Remove temporary files: