Skip to content

Commit 005aabb

Browse files
mdi-odoomdi-odoo
committed
Add comprehensive README with architecture, quality standards, and usage guide
Covers: project overview, workflow diagram, 6 command types with decision tree, dynamic features, frontmatter spec, project structure, quality gates, scoring rubric, validation commands, subagent architecture, and development guide.
1 parent f2eda8e commit 005aabb

1 file changed

Lines changed: 351 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 351 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,351 @@
1+
# Platxa Command Generator
2+
3+
> Autonomous slash command creator for Claude Code CLI. Transforms natural language descriptions into production-ready commands through a multi-phase orchestrated workflow.
4+
>
5+
> **Maintained by**: [Platxa](https://platxa.com) | **License**: MIT | **Version**: 1.0.0
6+
7+
**54 files** | **63 tests** | **7 validators** | **4 subagents** | **6 command types**
8+
9+
---
10+
11+
## Overview
12+
13+
Platxa Command Generator is a [Claude Code skill](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/skills) that autonomously creates slash commands by orchestrating specialized subagents through a structured pipeline:
14+
15+
```
16+
User describes command
17+
↓
18+
┌─────────┐ ┌──────────────┐ ┌────────────┐ ┌────────────┐
19+
│ DISCOVER │ ──▶ │ ARCHITECTURE │ ──▶ │ GENERATE │ ──▶ │ VALIDATE │
20+
│ Research │ │ Type + Plan │ │ Write .md │ │ Score ≥7.0 │
21+
└─────────┘ └──────────────┘ └────────────┘ └─────┬──────┘
22+
│
23+
┌──────────────────┤
24+
│ < 7.0 │ ≥ 7.0
25+
┌────▼───┐ ┌────▼─────┐
26+
│ REWORK │ │ INSTALL │
27+
│ (max 2)│ │ Command │
28+
└────────┘ └──────────┘
29+
```
30+
31+
Each phase uses the Task tool to delegate to specialized subagents defined in `references/agents/`, ensuring deep expertise at every step.
32+
33+
---
34+
35+
## Quick Start
36+
37+
```bash
38+
# Install as a skill
39+
git clone https://github.com/platxa/platxa-command-generator.git
40+
cd platxa-command-generator
41+
./scripts/install-command.sh . --user
42+
43+
# Then in any Claude Code session:
44+
/platxa-command-generator
45+
```
46+
47+
Or invoke directly:
48+
49+
```bash
50+
/platxa-command-generator "Create a command that runs tests with coverage for a specific file"
51+
```
52+
53+
---
54+
55+
## Command Types
56+
57+
The generator classifies commands into six types based on complexity and features:
58+
59+
| Type | Frontmatter | Dynamic Features | Complexity | Use Case |
60+
|------|-------------|-----------------|------------|----------|
61+
| **Basic** | None | None | Low | Simple instructions, checklists |
62+
| **Standard** | `description`, `allowed-tools` | None | Low-Medium | Tool-scoped team commands |
63+
| **Parameterized** | + `argument-hint` | `$1`, `$2` | Medium | Commands with user arguments |
64+
| **Interactive** | + `AskUserQuestion` | User prompts | Medium | Guided wizards, multiple choices |
65+
| **Workflow** | + `TodoWrite`, `Task` | Multi-phase | High | Complex multi-step processes |
66+
| **Plugin** | + `${CLAUDE_PLUGIN_ROOT}` | Plugin paths | Medium-High | Distributed plugin commands |
67+
68+
### Type Decision Tree
69+
70+
```
71+
Does the command need Claude to use specific tools?
72+
├── No → Basic
73+
└── Yes → Does it accept user arguments ($1, $2)?
74+
├── No → Standard
75+
└── Yes → Does it require interactive user input?
76+
├── No → Parameterized
77+
└── Yes → Does it have multiple phases with state?
78+
├── No → Interactive
79+
└── Yes → Is it distributed as a plugin?
80+
├── No → Workflow
81+
└── Yes → Plugin
82+
```
83+
84+
---
85+
86+
## Dynamic Features
87+
88+
Commands support four dynamic features that are resolved at invocation time:
89+
90+
| Feature | Syntax | Example | Resolution |
91+
|---------|--------|---------|------------|
92+
| Positional args | `$1`, `$2` | `/deploy staging` | `$1` = `staging` |
93+
| All arguments | `$ARGUMENTS` | `/search foo bar` | `$ARGUMENTS` = `foo bar` |
94+
| File reference | `@file` | User references a file | Content injected inline |
95+
| Bash execution | `` !`cmd` `` | `` !`git branch --show-current` `` | Output replaces block |
96+
| Plugin root | `${CLAUDE_PLUGIN_ROOT}` | Plugin-relative paths | Absolute plugin path |
97+
98+
---
99+
100+
## Frontmatter Specification
101+
102+
All frontmatter fields are **optional** for commands (Basic type requires none):
103+
104+
```yaml
105+
---
106+
description: generate unit tests for specified module # ≤60 chars, lowercase verb
107+
allowed-tools: # Valid Claude Code tools
108+
- Read
109+
- Write
110+
- Bash(pytest:*) # Bash filters supported
111+
argument-hint: "[module-path] [options]" # Bracket format
112+
model: sonnet # opus, sonnet, or haiku
113+
disable-model-invocation: false # Prevent AI self-invocation
114+
---
115+
```
116+
117+
Valid tools: `Read`, `Write`, `Edit`, `MultiEdit`, `Glob`, `Grep`, `LS`, `Bash`, `Task`, `WebFetch`, `WebSearch`, `AskUserQuestion`, `TodoWrite`, `KillShell`, `BashOutput`, `NotebookEdit`
118+
119+
---
120+
121+
## Project Structure
122+
123+
```
124+
platxa-command-generator/
125+
├── SKILL.md # Main orchestrator entry point
126+
├── references/
127+
│ ├── agents/ # 4 subagent prompt definitions
128+
│ │ ├── discovery-agent.md # Research domain & existing commands
129+
│ │ ├── architecture-agent.md # Determine command type & structure
130+
│ │ ├── generation-agent.md # Create command .md file
131+
│ │ └── validation-agent.md # Quality scoring & compliance
132+
│ ├── templates/ # 8 command type templates
133+
│ │ ├── basic-template.md # No frontmatter
134+
│ │ ├── standard-template.md # With allowed-tools
135+
│ │ ├── parameterized-template.md # $1/$2 + argument-hint
136+
│ │ ├── interactive-template.md # AskUserQuestion workflows
137+
│ │ ├── workflow-template.md # Multi-phase + state
138+
│ │ ├── plugin-template.md # ${CLAUDE_PLUGIN_ROOT} paths
139+
│ │ ├── command-templates.md # Type selection guide
140+
│ │ └── anti-patterns.md # Common mistakes to avoid
141+
│ ├── patterns/ # 16 implementation patterns
142+
│ │ ├── command-types.md # Type classification decision tree
143+
│ │ ├── frontmatter-generator.md # Field creation rules
144+
│ │ ├── frontmatter-validator.md # Validation rules & constraints
145+
│ │ ├── argument-patterns.md # $1/$2/$ARGUMENTS usage
146+
│ │ ├── file-reference-patterns.md # @file reference patterns
147+
│ │ ├── bash-execution-patterns.md # !`bash` safety & portability
148+
│ │ ├── naming-conventions.md # Command naming rules
149+
│ │ ├── domain-discovery.md # Research strategies
150+
│ │ ├── content-quality-scorer.md # Quality evaluation criteria
151+
│ │ ├── token-budget.md # Budget limits & estimation
152+
│ │ ├── state-machine.md # Workflow state transitions
153+
│ │ ├── phase-transitions.md # Phase progression rules
154+
│ │ ├── quality-gate.md # Quality thresholds
155+
│ │ ├── error-handling.md # Error recovery patterns
156+
│ │ ├── context-handoff.md # Agent-to-agent data flow
157+
│ │ └── subagent-dispatch.md # Task tool delegation
158+
│ └── spec/
159+
│ └── directory-layout.md # Repository structure spec
160+
├── scripts/ # 7 validation & utility scripts
161+
│ ├── validate-all.sh # Orchestrates all validators
162+
│ ├── validate-structure.sh # File structure checks
163+
│ ├── validate-frontmatter.sh # YAML frontmatter validation
164+
│ ├── count-tokens.py # Token & line budget enforcement
165+
│ ├── security-check.sh # Dangerous pattern scanning
166+
│ ├── install-command.sh # Install to user/project/plugin
167+
│ └── check-duplicates.py # Duplicate name/description detection
168+
├── tests/ # 63 tests across 6 modules
169+
│ ├── conftest.py # Pytest fixtures (real file ops)
170+
│ ├── helpers.py # Shared test utilities
171+
│ ├── test_validate_frontmatter.py # Frontmatter validation tests
172+
│ ├── test_validate_structure.py # Structure validation tests
173+
│ ├── test_count_tokens.py # Token budget tests
174+
│ ├── test_security_check.py # Security scanning tests
175+
│ ├── test_check_duplicates.py # Duplicate detection tests
176+
│ └── test_integration.py # Full pipeline tests
177+
├── assets/
178+
│ └── command-template/
179+
│ └── command.md # Blank command template
180+
└── commands/ # Generated commands output
181+
```
182+
183+
---
184+
185+
## Quality Standards
186+
187+
Every generated command passes through a multi-gate validation pipeline:
188+
189+
| Gate | Threshold | Type | Description |
190+
|------|-----------|------|-------------|
191+
| Structure | Pass | Hard | File exists, readable, `.md` extension, not empty |
192+
| Frontmatter | Pass | Hard | Valid YAML, all fields within constraints |
193+
| Token Budget | < 4,000 | Hard | Recommended < 2,000 tokens |
194+
| Line Budget | < 600 | Hard | Recommended < 300 lines |
195+
| Security | Pass | Hard | No dangerous patterns or hardcoded credentials |
196+
| Content Quality | ≥ 7.0/10 | Hard | Clear instructions, examples, no placeholders |
197+
| Duplicates | Pass | Hard | No name collisions or high-similarity matches |
198+
199+
### Scoring Rubric
200+
201+
| Category | Weight | Criteria |
202+
|----------|--------|----------|
203+
| Structure | 20% | Valid file, proper frontmatter |
204+
| Content Quality | 30% | Clear instructions, realistic examples |
205+
| Dynamic Features | 15% | Correct argument handling, safe bash |
206+
| Token Efficiency | 15% | Within budget limits |
207+
| Security | 10% | No dangerous patterns |
208+
| Completeness | 10% | Examples, edge cases, output format |
209+
210+
---
211+
212+
## Installation Methods
213+
214+
### Install as a Skill (Recommended)
215+
216+
```bash
217+
./scripts/install-command.sh . --user # Install to ~/.claude/skills/
218+
./scripts/install-command.sh . --project # Install to .claude/skills/
219+
```
220+
221+
### Install Generated Commands
222+
223+
```bash
224+
# Install a generated command
225+
./scripts/install-command.sh commands/my-command.md --user # ~/.claude/commands/
226+
./scripts/install-command.sh commands/my-command.md --project # .claude/commands/
227+
./scripts/install-command.sh commands/my-command.md --plugin my-plugin # Plugin namespace
228+
```
229+
230+
### Manual Copy
231+
232+
```bash
233+
cp commands/my-command.md ~/.claude/commands/
234+
```
235+
236+
---
237+
238+
## Validation
239+
240+
```bash
241+
# Run all validators on a command
242+
./scripts/validate-all.sh commands/my-command.md
243+
244+
# Run individual validators
245+
./scripts/validate-structure.sh commands/my-command.md
246+
./scripts/validate-frontmatter.sh commands/my-command.md
247+
python3 scripts/count-tokens.py commands/my-command.md
248+
./scripts/security-check.sh commands/my-command.md
249+
python3 scripts/check-duplicates.py commands/my-command.md
250+
251+
# Self-validate the generator
252+
./scripts/validate-all.sh .
253+
```
254+
255+
Example output:
256+
257+
```
258+
Validation Results for: my-command.md
259+
══════════════════════════════════════
260+
Structure: PASS
261+
Frontmatter: PASS
262+
Token Budget: PASS (850 / 4000)
263+
Security: PASS
264+
Content Quality: 7.2 / 6.0 PASS
265+
──────────────────────────────────────
266+
Overall Score: 8.1 / 7.0 PASS
267+
Result: PASS
268+
══════════════════════════════════════
269+
```
270+
271+
---
272+
273+
## Development
274+
275+
### Prerequisites
276+
277+
- Python 3.10+
278+
- `pip install -r requirements.txt` (tiktoken, pyyaml, pytest)
279+
280+
### Commands
281+
282+
```bash
283+
# Run all tests
284+
pytest tests/ -v
285+
286+
# Run specific test module
287+
pytest tests/test_validate_frontmatter.py -v
288+
289+
# Run tests matching pattern
290+
pytest -k "test_valid_description"
291+
292+
# Validate the generator itself
293+
./scripts/validate-all.sh .
294+
295+
# Check token budget
296+
python3 scripts/count-tokens.py .
297+
```
298+
299+
### Testing Philosophy
300+
301+
All tests use **real file system operations** — no mocks, no simulations. Tests create actual `.md` files in temporary directories, execute validation scripts via subprocess, and verify real output.
302+
303+
---
304+
305+
## Subagent Architecture
306+
307+
The generator delegates each workflow phase to a specialized subagent via the Task tool:
308+
309+
| Phase | Agent | Subagent Type | Purpose |
310+
|-------|-------|---------------|---------|
311+
| Discovery | `discovery-agent.md` | `Explore` | Research domain, analyze existing commands |
312+
| Architecture | `architecture-agent.md` | `general-purpose` | Classify type, design structure |
313+
| Generation | `generation-agent.md` | `general-purpose` | Create command `.md` file |
314+
| Validation | `validation-agent.md` | `general-purpose` | Score quality, check compliance |
315+
316+
Each agent receives context from the previous phase via structured JSON handoffs defined in `references/patterns/context-handoff.md`.
317+
318+
---
319+
320+
## Related Projects
321+
322+
| Project | Description |
323+
|---------|-------------|
324+
| [platxa-skill-generator](https://github.com/platxa/platxa-skill-generator) | Generates Claude Code skills (multi-file directories) |
325+
| [platxa-agent-generator](https://github.com/platxa/platxa-agent-generator) | Generates Claude Code plugin agents |
326+
| [platxa-command-builder](https://github.com/platxa/platxa-skill-generator) | Skill for manually building commands (non-autonomous) |
327+
328+
---
329+
330+
## Contributing
331+
332+
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full submission guide.
333+
334+
```bash
335+
# Quick validation before submitting
336+
pytest tests/ -v
337+
./scripts/validate-all.sh .
338+
python3 scripts/count-tokens.py .
339+
```
340+
341+
Commit format: `type(scope): description` (e.g., `feat(templates): add workflow template`)
342+
343+
---
344+
345+
## License
346+
347+
MIT License - See [LICENSE](LICENSE) for details.
348+
349+
---
350+
351+
*Created by [DJ Patel](https://platxa.com) | Platxa*

0 commit comments

Comments
 (0)