Generate or update app-specs.md documentation from feature specifications
Generates a comprehensive status dashboard by scanning all feature specs in `/specs/` and creating/updating `app-specs.md` with completion percentages, feature lists, and progress indicators. Use this after completing features or at sprint end to maintain accurate project documentation.
/plugin marketplace add dbalanco/perseon-marketplace/plugin install dbalanco-documentation-tools-plugins-documentation-tools-2@dbalanco/perseon-marketplaceGenerate or update the /specs/app-specs.md document by analyzing all feature implementation plans in the project.
/specs/ for requirements.md and implementation-plan.md filesapp-specs.md document with:
package.json (if available)First, verify that tsx is installed:
which tsx
If tsx is not found, inform the user:
ā Error: tsx is not installed.
To use this command, install tsx globally:
npm install -g tsx
# or
pnpm add -g tsx
Then run this command again.
Do not proceed if tsx is not installed.
Check that the default spec directory exists:
test -d /specs && echo "exists" || echo "not found"
If the directory doesn't exist, ask the user:
The default spec directory `/specs/` was not found.
Would you like to:
1. Create it now
2. Specify a different directory
3. Cancel
Execute the generator in non-destructive mode:
tsx ${CLAUDE_PLUGIN_ROOT}/skills/app-spec-generator/scripts/update.ts
Important: This is the default, safe mode that generates/updates app-specs.md WITHOUT modifying any spec folders.
After the script completes successfully, display a summary:
ā
Updated app-specs.md:
- [X] features processed
- [Y]% overall completion
- [A] completed, [B] in progress, [C] planned
- [N] categories tracked
š File: /specs/app-specs.md
Would you like me to open the generated file so you can review it?
If the user wants to review, use the Read tool to show the file contents or relevant sections.
If the script fails, check the error message:
Common errors:
tsx not found:
Explain that tsx must be installed globally
Provide installation command
Permission denied:
Check file permissions on /specs/
Suggest: chmod 755 /specs/
No specs found:
Verify spec folders exist in /specs/
Confirm folders have requirements.md or implementation-plan.md files
Script errors:
Show the error message
Suggest checking the troubleshooting reference:
${CLAUDE_PLUGIN_ROOT}/skills/app-spec-generator/references/troubleshooting.md
ā ļø WARNING: Only use cleanup mode if the user explicitly requests it.
The --cleanup flag is DESTRUCTIVE and will:
/specs/.archive/[timestamp]//specs/ after archivalOnly run cleanup mode if the user:
If the user confirms they want cleanup mode:
Explain what will happen:
ā ļø Cleanup Mode Warning:
This will:
- Archive all spec folders to /specs/.archive/[timestamp]/
- Remove original spec folders from /specs/
- Leave only app-specs.md as the documentation source
All folders will be backed up before removal, and the operation can be rolled back if something goes wrong.
Are you sure you want to proceed? (yes/no)
If confirmed, run:
tsx ${CLAUDE_PLUGIN_ROOT}/skills/app-spec-generator/scripts/update.ts --cleanup
Show detailed results:
ā
Updated app-specs.md:
- [X] features processed
- [Y]% overall completion
- [A] completed, [B] in progress, [C] planned
- [N] categories tracked
š¦ Archive Created:
- Location: /specs/.archive/[timestamp]/
- [M] folders archived
- Archive validated successfully ā
šļø Cleanup Completed:
- [M] spec folders removed from /specs/
- All folders safely backed up to archive
- Rollback available at archive location if needed
š File: /specs/app-specs.md
If cleanup fails:
ā ļø Cleanup Failed:
The script detected an issue and automatically rolled back changes.
Your spec folders are safe and unchanged.
Error: [error message]
The generated app-specs.md file is still available, but folder cleanup did not complete.
User: /update-specs
Claude:
User: /update-specs and clean up the folders
Claude:
User: /update-specs but use ./docs/features instead
Claude:
If the user prefers, they can also run:
With npm/pnpm (if configured):
pnpm update-specs
Directly with tsx:
tsx ${CLAUDE_PLUGIN_ROOT}/skills/app-spec-generator/scripts/update.ts
With cleanup:
tsx ${CLAUDE_PLUGIN_ROOT}/skills/app-spec-generator/scripts/update.ts --cleanup
Use this command when the user:
--cleanup flag)--cleanup flag is usedThe documentation generator system:
/specs/ (excluding itself and archives)[x] vs [ ] to calculate completion percentagesFeatures are automatically organized into these categories based on folder names:
When running this command: