| name | project-guide |
| description | Guide users through the Shebang workflow - kanban, skills, commands, and development process. Use when users are new, confused, or ask how to use Shebang features. |
Project Guide
Helps users understand and navigate the Shebang development workflow.
When to Use
- User is new to Shebang
- User asks "how do I..."
- User seems confused about workflow
- User asks about available features
Key Concepts to Explain
The Kanban Board
Access at http://localhost:8080 after running python3 .shebang/web/server.py
Columns:
- Backlog - Future work, ideas, planned features
- In Progress - Currently being worked on
- Review - Ready for testing/review
- Done - Completed work
How to use:
- Add tasks via dashboard or API
- Drag cards between columns as work progresses
- Click cards to see details and artifacts
- Tasks link to related documents
Available Commands
| Command | What It Does |
|---|---|
/new |
Create a new project in current directory |
/commit |
Run quality checks and commit with proper format |
Available Skills
Skills are automatically invoked based on context:
| Skill | When Used |
|---|---|
document-sync |
Updating text across multiple files |
commit-quality |
Before git commits |
kanban-sync |
Managing task board |
best-practices |
Setting up new projects |
docs-generator |
Updating documentation |
The Development Flow
1. Add task to Backlog (or use /new for new projects)
↓
2. Move to In Progress when starting work
↓
3. Write code (guardrails enforce quality)
↓
4. Move to Review when ready
↓
5. Use /commit to commit with quality checks
↓
6. Move to Done when complete
↓
7. docs-generator updates documentation
Guardrails
Automatic protections that run on every action:
- Secrets Detection - Blocks API keys, passwords
- Quality Checks - Blocks anti-patterns
- Command Safety - Blocks dangerous shell commands
Project Structure
your-project/
├── .shebang/ # Project data
│ ├── kanban.json # Your task board
│ ├── metrics.json # Productivity tracking
│ └── config.yaml # Project config
├── .gitignore
└── README.md
Common Questions
"How do I start a new project?"
Type /new and answer the questions.
A new folder is created with everything set up.
"How do I see my tasks?"
Run: python3 .shebang/web/server.py
Open: http://localhost:8080
"How do I add a task?"
Click "+ Add Task" in the dashboard
Or use the API:
curl -X POST http://localhost:8080/api/kanban/task \
-d '{"title": "My task", "description": "Details"}'
"How do I commit my work?"
Type /commit
Quality checks run automatically.
Commit message is formatted properly.
"What if a guardrail blocks me?"
Read the error message - it explains what's wrong.
Fix the issue (remove secret, fix anti-pattern, etc.)
Try again.
Onboarding Flow
For new users, walk through:
- Start the dashboard - Show them the kanban
- Create a task - Add something to backlog
- Write some code - Let guardrails demonstrate
- Commit - Show the /commit flow
- Complete task - Move to done, see docs update
Example Session
User: I'm new, how does this work?
Agent: Welcome to Shebang! Here's the quick tour:
1. Your project dashboard is at localhost:8080
Run: python3 .shebang/web/server.py
2. Add tasks to the Backlog column
3. Move tasks to "In Progress" when you start work
4. Write code - guardrails automatically:
- Block secrets
- Enforce quality
- Catch anti-patterns
5. Type /commit when ready to save
6. Move tasks to Done - documentation updates automatically
Want me to walk you through any of these?