acia-psg-generator

name	acia-psg-generator
description	AI explores the workspace and creates/updates a Project Structure Guide (PSG). Use when asked to "create PSG", "generate PSG", "update PSG", "make PSG", "Generate Project Structure Guide", "Create Project Structure Guide", "create Context Index", "analyze workspace structure", "organize folder structure", "PSGを作って", "PSGを作成して", "PSGを更新して", "PSGを生成して", "PSG作成", "Project Structure Guideを作成して", "Project Structure Guideを更新して", "プロジェクトの構造をまとめて", "ワークスペースの構造を分析して", "フォルダ構成を整理して". Do NOT use for README generation, skill definition creation (acia-skill-creator), or general document creation.
compatibility	Claude.ai / Claude Code / GitHub Copilot Agent
license	MIT
metadata	{"author":"acia","version":"1.0.0","category":"workspace-analysis"}

PSG Generation Skill

Overview

Explores the workspace and creates/updates a "Project Structure Guide (PSG)" that helps AI understand the asset layout (what is where) and inter-asset dependencies. A PSG is a structural map; it does not include operational procedures such as build steps, deployment steps, or execution commands.

Absolute Rules

CRITICAL — The following are the highest-priority rules across this entire skill. They must also be enforced when delegating work to sub-agents.

1. Output format compliance: PSG output format to files must follow the content defined in references/_common/output-spec.md
2. Continuous execution flow compliance (applies to both normal execution and fallback execution):
   • Work through Phases in order within ## Execution Procedure, and upon completing each Phase, immediately proceed to the next Phase
   • The ask_questions call in Phase 0 is mandatory and must not be omitted or skipped (Phase 0 is excluded from autonomous execution)
   • After Phase 0 completion, from Phase 1 onward, work autonomously on the AI side until the final report is complete
   • Applicable scope: Applies to both sub-agent delegated execution and fallback direct execution. During fallback execution, do not output Phase progress or intermediate results to chat. The final report after Phase 3 completion is the only user-facing output
3. Reference file mandatory reading: Read reference files with read_file before working. The same applies when delegating work to each sub-agent. No output, analysis, or writing is permitted before reading is complete
4. Fallback procedure compliance: If a tool is unavailable, follow the fallback procedure for that phase. Only if no fallback procedure exists either, halt processing and report to the user. Do not execute independently without reading the fallback procedure. Sub-agent delegation fallback condition: Applies only when sub-agent delegation tools (represented by runSubagent / Task) do not exist in the tool list. If they exist in the list but cannot be called due to runtime constraints, do not apply fallback — instead report the situation to the user and request guidance
5. Information consolidation in final report: Work/validation results, decisions, and correction logs must be recorded only in the final report (chat response). They must not be included in the PSG output file or in intermediate reports during work
6. File operations by main only, once: File writing and convert_psg.ps1 execution are performed by the main agent directly in Phase 3. Sub-agents (Phase 1 and Phase 2) only return text and must not perform any file writing or terminal execution.

Reference File Index

Paths are constructed relative to {skill-base-path} (the absolute path of the directory where SKILL.md resides)

Name	Path	Type	Scope
Output Spec	{skill-base-path}/references/_common/output-spec.md	Specification	Phase 1, 2 shared
Output Examples	{skill-base-path}/references/examples/output-examples.md	Examples	Phase 1, 2 shared
Exclusion Rules	{skill-base-path}/references/phase-1-explore/exclusion-rules.md	Specification	Phase 1
Exploration Guide	{skill-base-path}/references/phase-1-explore/exploration-guide.md	Procedure	Phase 1
Phase 1 Dispatch	{skill-base-path}/references/phase-1-explore/_dispatch.md	Dispatch	Phase 1
Validation Checklist	{skill-base-path}/references/phase-2-validate-write/validation-checklist.md	Checklist	Phase 2
Phase 2 Dispatch	{skill-base-path}/references/phase-2-validate-write/_dispatch.md	Dispatch	Phase 2

Tool Mapping

This skill uses the following abstract capability names. Match them against the execution environment's tool list to use the corresponding tools:

Abstract Capability	Claude.ai	Claude Code	GitHub Copilot Agent
Sub-agent delegation	runSubagent	Task	runSubagent
User question	ask_questions	AskUserQuestion	ask_questions
File read	read_file	Read	read_file

Execution Procedure

Phase 0: Output Destination Confirmation (Main Direct Execution)

IMPORTANT — This phase is excluded from autonomous execution (see Absolute Rule #2). Unless a fallback condition is met, always call ask_questions with the following fixed parameters and wait for the user's response. Omitting or skipping the call is not permitted (modifying, omitting, or adding parameters is also not permitted):

header: Output Destination
question: Where should the Project Structure Guide be output?
options:
  - .github/copilot-instructions.md (GitHub Copilot Custom Instructions — standard)
  - AGENT.md (root agent instruction file)
  - CLAUDE.md (root)
allowFreeformInput: true

Fixed values (do not confirm with user): Analysis scope = entire workspace / Output granularity = expand to sub-packages / Replace existing PSG if present, create new if not

Fallback: Apply fallback only when the ask_questions tool does not exist in the tool list (is not registered). If the tool exists in the list but cannot be called due to mode constraints or permission constraints, do not apply fallback — instead report the situation to the user and request guidance. When fallback is applied, fix the output destination to AGENT.md and proceed immediately to Phase 1 (when using Claude Code, check the workspace root with list_dir and prefer CLAUDE.md if it exists). Do not confirm with or report to the user when fallback is applied. Fixed values and the fixed destination filename are recorded only in the final report.

Result validation: Output destination is confirmed (via ask_questions response or fallback fixed value)

Phase 1: Exploration & Analysis (Sub-Agent Delegation)

IMPORTANT — The main agent must not perform workspace exploration or analysis directly (see Absolute Rules #2 and #3). Always delegate to a sub-agent via the sub-agent delegation tool (runSubagent / Task).

Launch a sub-agent using the sub-agent delegation tool (runSubagent / Task).

dispatch: references/phase-1-explore/_dispatch.md

description: "PSG Phase 1: Workspace Exploration & Analysis"

prompt construction: Build the sub-agent delegation tool's prompt parameter from the following 4 elements:

1. Work instruction: "Read {skill-base-path}/references/phase-1-explore/_dispatch.md with read_file and execute work according to its procedure"
2. Input parameter actual values: {workspace-root} = workspace root path, {skill-base-path} = absolute path of the directory where this SKILL.md resides
3. Prior phase results: None (Phase 1 is the first work phase)
4. Return value requirements: Return results in the format below

Input parameters:

• {workspace-root}: Workspace root path
• {skill-base-path}: Absolute path of the directory where this skill's SKILL.md resides

Return value requirements:

• Project summary (tech stack, module composition)
• Category classification results table (category name, folder path, role, determination rationale)
• Parallel instance information (concrete name list of placeholder-mapped items)
• Navigation Guide material

Fallback: Apply the sub-agent delegation fallback condition from Absolute Rule #4.

Result validation (gate): Verify all of the following. If any is not met, do not proceed to Phase 2 — report to the user and halt:

• Category classification results contain at least one folder path, and the tech stack is identified
• The return value text does not contain file operation reports (wording including "wrote", "created", "updated", "output to file")

Next step: Per Absolute Rule #2, immediately begin Phase 2.

Phase 2: PSG Text Generation (Sub-Agent Delegation)

IMPORTANT — The main agent must not generate PSG text directly (see Absolute Rules #1, #2, and #3). Always delegate to a sub-agent via the sub-agent delegation tool (runSubagent / Task). Generation in a format not conforming to the output-spec.md output template is not permitted.

Before using the sub-agent delegation tool, the main agent performs the following:

Pre-processing (main direct execution): Read the full content of {output-path} with read_file and extract the <!-- PSG:START --> to <!-- PSG:END --> range. If the range exists, use its content as {existing-psg}. If it does not exist, set {existing-psg} = empty string. If the file itself does not exist, likewise use empty string.

Then launch a sub-agent using the sub-agent delegation tool (runSubagent / Task).

dispatch: references/phase-2-validate-write/_dispatch.md

description: "PSG Phase 2: PSG Text Generation & Validation"

prompt construction: Build the sub-agent delegation tool's prompt parameter from the following 4 elements:

1. Work instruction: "Read {skill-base-path}/references/phase-2-validate-write/_dispatch.md with read_file and execute work according to its procedure"
2. Input parameter actual values: {workspace-root}, {skill-base-path}, {existing-psg} actual values
3. Prior phase results: Phase 1 structured exploration & analysis results (extract only the ## Exploration & Analysis Results section content)
4. Return value requirements: Return results in the format below

Input parameters:

• {workspace-root}: Workspace root path
• {skill-base-path}: Absolute path of the directory where this skill's SKILL.md resides
• {existing-psg}: Existing PSG text extracted in Phase 2 pre-processing (may be empty string)
• {analysis-result}: Phase 1 structured exploration & analysis results

Return value requirements:

• Generated PSG text (complete text including <!-- PSG:START --> through <!-- PSG:END -->)
• Validation results (content checks T1, T2, T4, T5, T6, T7, T8, T9; AI judgments J1–J9)
• Auto-correction details (if applicable)
• Category count
• Decision notes
• If any folders were provisionally classified as "Other": folder names and reasons

Fallback: Apply the sub-agent delegation fallback condition from Absolute Rule #4.

Result validation: All validation item results and PSG text are reported.

Next step: Per Absolute Rule #2, immediately begin Phase 3.

Phase 3: File Writing & Encoding Conversion (Main Direct Execution)

IMPORTANT — This Phase must not be delegated to sub-agents; the main agent executes directly (see Absolute Rule #6).

Procedure (fixed sequence):

1. Full read: Read the full content of {output-path} with read_file. If the file does not exist, use empty string.

2. 3-way split: Split the file content into the following 3 parts:

   • pre: Content before <!-- PSG:START -->
   • psg: PSG text returned by Phase 2 (including <!-- PSG:START --> through <!-- PSG:END -->)
   • post: Content after <!-- PSG:END -->
   • If no existing PSG section: pre = entire file, post = empty string

3. Contamination removal: If pre contains any of the following headers, remove everything from that header line through the line immediately before the next section (removes Phase 1 internal data contamination):

   • ## Exploration & Analysis Results
   • ### Category Classification Results
   • ### Parallel Instance Information
   • ### Navigation Guide Material
   • Content wrapped in code blocks (```markdown / ```) is similarly removed
   • If removal was performed, record in the decision notes of the final report

4. Write (once only): Concatenate pre + psg + post and write to {output-path}. Either partial replacement via replace_string_in_file or full write via create_file / insert_edit_into_file is acceptable, but execute only once in this step.

5. Encoding conversion (unconditional execution): Immediately after write completion, execute the following command. Do not skip:

   & "{skill-base-path}/scripts/convert_psg.ps1" -OutputPath "{output-path}"
   

   For macOS / Linux:

   python3 "{skill-base-path}/scripts/convert_psg.py" "{output-path}"
   

   Skip only if the terminal tool is unavailable, and record "Encoding conversion not performed" in the final report.

6. Post-write validation: Read {output-path} with read_file and verify the following. If any is NG, report to the user and halt (do not auto-retry):

   • Exactly 1 instance of <!-- PSG:START --> exists
   • Exactly 1 instance of <!-- PSG:END --> exists
   • 0 instances of ## Exploration & Analysis Results (contamination removed)

Next step: Execute the final report. This is the only user-facing report in this skill (Absolute Rule #2).

Final Report (After Phase 3 Completion — The Only User-Facing Report)

Output the following to chat based on Phase 2 and Phase 3 results:

• Content checks (T1, T2, T4, T5, T6, T7, T8, T9): detection count and OK/NG for each ID
• AI judgments (J1–J9): result for each ID
• If auto-corrections were performed: list of correction details
• If contamination removal was performed: summary of removed content
• Encoding conversion execution result (performed / not performed)
• Work summary (including output destination and category count)
• Decision notes (module composition determination, category split rationale)
• If any folders were provisionally classified as "Other": folder names and reasons
• If unresolved items exist: items and proposed remediation

Performance Notes

IMPORTANT: Quality takes priority over speed.

• If result validation at any Phase shows deficiencies, consider re-execution