Project Creator

Guide creation and maintenance of project documentation in .project/ folder.

Quick Navigation

• Templates: assets/ folder
• Guides: references/ folder

When to Use

• Starting a new project
• Creating/updating .project/ documentation
• Planning user stories

Project Structure

.project/
├── about.md              # Project overview, goals, target audience
├── specs.md              # Technical specifications, versions
├── architecture.md       # System architecture with diagrams
├── project-context.md    # Cumulative decisions (optional)
└── stories/
    ├── stories.md        # Master list
    └── 001-story-name.md # Individual stories

Assets (Templates)

Guides (References)

Document Dependencies

about.md → specs.md → architecture.md → project-context.md → stories/

Workflow per Document

Standard Flow

1. Load guide from references/
2. Check if document exists — read and assess if yes
3. Create/update using template from assets/
4. Interview user with questions from guide
5. Draft content based on responses
6. Present draft, ask for feedback
7. Iterate until user confirms
8. Move to next document

Existing Documents

When documents already exist:

• Read and assess completion state
• Ask user: review/update or skip?
• Build on existing content — don't recreate
• Note gaps or inconsistencies

Communication Style

Always Do

• Ask one topic at a time
• Offer 2-3 formulation variants
• Explain technical concepts simply
• Summarize understanding before drafting
• Confirm before moving to next step

Never Do

• Assume answers
• Skip confirmation steps
• Use jargon without explanation
• Move to next document without confirmation
• Write specs without verifying latest versions

Example Interaction

Agent: Let's start with about.md. Can you describe what this project does in your own words?

User: It's an app for tracking expenses.

Agent: Great start! Here are some formulation options:

  1. "A personal finance app for tracking daily expenses"
  2. "An expense tracker that helps users manage spending"
  3. "A mobile app for recording and categorizing expenses"

  Which resonates most? Or combine elements?

User: Option 2, but for small businesses, not personal.

Agent: Updated formulation:

  "An expense tracker that helps small businesses
  manage spending and categorize business expenses."

  Does that capture it? Should we add reporting
  or team features?

Critical Rules

• NEVER assume project details — always ask
• ALWAYS offer formulation variants
• ALWAYS validate understanding with user
• NEVER proceed without user confirmation
• ALWAYS use templates from assets/
• NEVER allow version downgrades (only upgrades)

Example Questions

Questions are examples — adapt to each unique project:

About.md

• Can you describe your project in one sentence?
• What frustration does this solve for users?
• If you could only build 3 features, what would they be?
• How will you know if the project is successful?
• What will this project definitely NOT do?

Specs.md

• What devices/browsers must be supported?
• How many concurrent users do you expect?
• Is there existing infrastructure to integrate with?
• What's the team's experience with [technology]?
• Are there any compliance requirements?

Architecture.md

• What are the main parts of the system?
• How should components communicate?
• What data flows exist?
• How will it scale?
• How is it secured?

Stories

• What's absolutely essential for launch?
• What can wait until later?
• What's the logical order of features?
• Does feature X need feature Y first?

Helping Non-Technical Users

When user lacks technical knowledge:

1. Explain options simply

• "React is great for interactive UIs, Vue is simpler to learn"
• "PostgreSQL is reliable for structured data, MongoDB for flexible schemas"

1. Use analogies

• "The API is like a waiter taking orders to the kitchen"
• "The database is like a filing cabinet"
• "The cache is like a notepad for quick lookups"

1. Make recommendations with reasoning

• "Given your expected user count, I recommend..."
• "Since you need real-time updates, this pattern..."

1. Explain trade-offs

• Performance vs. simplicity
• Feature richness vs. learning curve
• Cost vs. scalability

Links

• Agent Skills Specification