workflow-agent-cli 1.1.2

package/templates/PROJECT_TEMPLATE_README.md

@@ -0,0 +1,347 @@
+# Project Template README
+
+> **Purpose**: This document provides guidance for using the ProjectHub guidelines as a template for new projects. It explains which files to copy, what to customize, and how to adapt the patterns to different tech stacks.
+
+---
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Files to Copy](#files-to-copy)
+3. [Customization Guide](#customization-guide)
+4. [Tech Stack Adaptations](#tech-stack-adaptations)
+5. [Checklist for New Projects](#checklist-for-new-projects)
+
+---
+
+## Overview
+
+The ProjectHub guidelines provide a comprehensive framework for:
+
+- **Agent-assisted development** - Rules for AI coding assistants
+- **Code organization** - Single source of truth patterns
+- **Quality assurance** - Testing and review strategies
+- **Workflow standardization** - Branching and deployment
+
+These patterns are designed to be **tech-stack agnostic** at their core, with specific sections that need customization for each project.
+
+---
+
+## Files to Copy
+
+### Required Files (Copy These)
+
+| File                                       | Purpose          | Customization Level        |
+| ------------------------------------------ | ---------------- | -------------------------- |
+| `guidelines/AGENT_EDITING_INSTRUCTIONS.md` | AI editing rules | Medium - Update file paths |
+| `guidelines/BRANCHING_STRATEGY.md`         | Git workflow     | Low - Update scopes list   |
+| `guidelines/TESTING_STRATEGY.md`           | Testing patterns | High - Update tooling      |
+| `.github/PULL_REQUEST_TEMPLATE.md`         | PR template      | Low - Update scopes list   |
+
+### Recommended Files (Create Fresh)
+
+| File                                   | Purpose         | Why Create Fresh         |
+| -------------------------------------- | --------------- | ------------------------ |
+| `guidelines/SINGLE_SOURCE_OF_TRUTH.md` | File locations  | Unique to each project   |
+| `guidelines/LIBRARY_INVENTORY.md`      | Dependencies    | Different for each stack |
+| `guidelines/DEPLOYMENT_STRATEGY.md`    | Deployment flow | Platform-specific        |
+
+### Directory Structure
+
+```
+your-project/
+├── .github/
+│   └── PULL_REQUEST_TEMPLATE.md    # Copy from template
+├── guidelines/
+│   ├── AGENT_EDITING_INSTRUCTIONS.md   # Copy + customize
+│   ├── BRANCHING_STRATEGY.md           # Copy + update scopes
+│   ├── TESTING_STRATEGY.md             # Copy + update tools
+│   ├── SINGLE_SOURCE_OF_TRUTH.md       # Create fresh
+│   ├── LIBRARY_INVENTORY.md            # Create fresh
+│   ├── DEPLOYMENT_STRATEGY.md          # Create fresh
+│   └── PROJECT_TEMPLATE_README.md      # Optional meta-doc
+└── ...
+```
+
+---
+
+## Customization Guide
+
+### AGENT_EDITING_INSTRUCTIONS.md
+
+#### Sections to Keep As-Is
+
+- File analysis checklist format
+- Library usage policy
+- PR workflow structure
+- Quality standards
+
+#### Sections to Customize
+
+| Section                  | What to Change                                   |
+| ------------------------ | ------------------------------------------------ |
+| Required File Checklists | Update file paths for your project structure     |
+| Import Ordering          | Adjust for your project's conventions            |
+| Architecture Rules       | Update for your framework (not Next.js specific) |
+| Data Flow                | Document your auth/authorization patterns        |
+
+#### Example Adaptations
+
+**For a Python/FastAPI Project:**
+
+```markdown
+## Required Files by Change Type
+
+### Adding API Endpoint
+
+- [ ] Endpoint in `app/api/routes/`
+- [ ] Schema in `app/schemas/`
+- [ ] Tests in `tests/api/`
+- [ ] Types in `app/models/`
+```
+
+**For a React SPA (Vite):**
+
+```markdown
+## Required Files by Change Type
+
+### Adding Feature
+
+- [ ] Component in `src/components/`
+- [ ] Hook in `src/hooks/` (if stateful)
+- [ ] Types in `src/types/`
+- [ ] Tests in `src/__tests__/`
+```
+
+### BRANCHING_STRATEGY.md
+
+#### Sections to Keep As-Is
+
+- Branch naming format
+- PR title format (conventional commits)
+- Workflow steps
+- Merge requirements structure
+
+#### Sections to Customize
+
+| Section             | What to Change                           |
+| ------------------- | ---------------------------------------- |
+| Allowed Scopes      | Define scopes for your project's domains |
+| Review Requirements | Adjust for your team size                |
+| Hotfix Workflow     | Update deployment references             |
+
+#### Defining Scopes
+
+Choose scopes that match your project's domains:
+
+**E-commerce Example:**
+
+```markdown
+| Scope      | Description                  |
+| ---------- | ---------------------------- |
+| `cart`     | Shopping cart functionality  |
+| `checkout` | Payment and order processing |
+| `products` | Product catalog, search      |
+| `users`    | User accounts, profiles      |
+| `orders`   | Order management             |
+| `admin`    | Admin dashboard              |
+```
+
+**SaaS Example:**
+
+```markdown
+| Scope          | Description              |
+| -------------- | ------------------------ |
+| `billing`      | Subscriptions, payments  |
+| `dashboard`    | Main dashboard           |
+| `reports`      | Analytics and reporting  |
+| `integrations` | Third-party integrations |
+| `teams`        | Team management          |
+| `settings`     | Configuration            |
+```
+
+### TESTING_STRATEGY.md
+
+#### Sections to Keep As-Is
+
+- Testing pyramid concept
+- Coverage requirements
+- Pre-merge checklist structure
+
+#### Sections to Customize
+
+| Section             | What to Change                             |
+| ------------------- | ------------------------------------------ |
+| Test Tooling        | Update for your stack (Jest, pytest, etc.) |
+| Test Patterns       | Update examples for your framework         |
+| E2E Configuration   | Update for your E2E tool                   |
+| Test Infrastructure | Update setup files                         |
+
+#### Tooling Adaptations
+
+**For React + Jest:**
+
+```markdown
+## Unit Testing with Jest
+
+### Configuration
+
+- Config: `jest.config.js`
+- Setup: `src/setupTests.ts`
+- Run: `npm test`
+```
+
+**For Python + pytest:**
+
+```markdown
+## Unit Testing with pytest
+
+### Configuration
+
+- Config: `pyproject.toml` or `pytest.ini`
+- Fixtures: `tests/conftest.py`
+- Run: `pytest`
+```
+
+### PULL_REQUEST_TEMPLATE.md
+
+#### Sections to Keep As-Is
+
+- Type of Change checkboxes
+- Quality Checklist
+- Breaking Changes section
+- New Dependencies section
+
+#### Sections to Customize
+
+| Section                 | What to Change              |
+| ----------------------- | --------------------------- |
+| Scope checkboxes        | Update to match your scopes |
+| Files Changed Checklist | Update file paths           |
+| Testing Performed       | Update test commands        |
+
+---
+
+## Tech Stack Adaptations
+
+### Next.js → Other React Frameworks
+
+| Concept        | Next.js        | Vite/CRA      | Remix              |
+| -------------- | -------------- | ------------- | ------------------ |
+| Server Actions | `app/actions/` | N/A (use API) | `app/routes/*.tsx` |
+| API Routes     | `app/api/`     | External API  | Loaders/Actions    |
+| SSR            | Automatic      | Manual        | Automatic          |
+| File routing   | `app/`         | React Router  | `app/routes/`      |
+
+### React → Vue/Svelte/Angular
+
+| Concept    | React           | Vue            | Svelte    | Angular         |
+| ---------- | --------------- | -------------- | --------- | --------------- |
+| Components | `.tsx`          | `.vue`         | `.svelte` | `.component.ts` |
+| State      | Context/Zustand | Pinia          | Stores    | Services        |
+| Hooks      | `hooks/`        | `composables/` | `stores/` | `services/`     |
+| Testing    | Vitest/RTL      | Vitest/VTU     | Vitest    | Karma/Jest      |
+
+### Supabase → Other Backends
+
+| Concept    | Supabase               | Firebase        | Prisma + PostgreSQL  |
+| ---------- | ---------------------- | --------------- | -------------------- |
+| Client     | `lib/supabase/`        | `lib/firebase/` | `lib/prisma/`        |
+| Auth       | Supabase Auth          | Firebase Auth   | NextAuth/Clerk       |
+| Types      | Generated              | N/A             | Generated            |
+| Migrations | `supabase/migrations/` | N/A             | `prisma/migrations/` |
+
+### Vercel → Other Platforms
+
+| Concept        | Vercel    | Netlify   | Railway   | AWS         |
+| -------------- | --------- | --------- | --------- | ----------- |
+| Preview URLs   | Automatic | Automatic | Manual    | Manual      |
+| Env Variables  | Dashboard | Dashboard | Dashboard | SSM         |
+| Rollback       | Dashboard | Dashboard | CLI       | CLI         |
+| Edge Functions | Yes       | Yes       | No        | Lambda@Edge |
+
+---
+
+## Checklist for New Projects
+
+### Initial Setup
+
+- [ ] Create `guidelines/` directory
+- [ ] Copy `AGENT_EDITING_INSTRUCTIONS.md` and customize
+- [ ] Copy `BRANCHING_STRATEGY.md` and update scopes
+- [ ] Copy `TESTING_STRATEGY.md` and update tooling
+- [ ] Copy `.github/PULL_REQUEST_TEMPLATE.md` and update scopes
+
+### Create Fresh Documents
+
+- [ ] Create `SINGLE_SOURCE_OF_TRUTH.md` with your file locations
+- [ ] Create `LIBRARY_INVENTORY.md` with your dependencies
+- [ ] Create `DEPLOYMENT_STRATEGY.md` for your platform
+
+### Validation
+
+- [ ] All file paths in guidelines match actual project structure
+- [ ] Scopes list covers all major areas of the project
+- [ ] Testing commands in guidelines actually work
+- [ ] PR template scopes match branching strategy scopes
+
+### Team Onboarding
+
+- [ ] Team has reviewed all guidelines
+- [ ] Guidelines are linked from main README
+- [ ] First few PRs use the new template
+- [ ] Iterate based on team feedback
+
+---
+
+## Template Maintenance
+
+### When to Update Guidelines
+
+- Adding major new feature area → Add new scope
+- Changing tech stack → Update tooling sections
+- New team members have questions → Clarify documentation
+- Recurring review comments → Add to checklist
+
+### Version Control
+
+Consider versioning your guidelines:
+
+```markdown
+<!-- At top of each file -->
+
+> **Version**: 1.0.0  
+> **Last Updated**: 2026-01-08  
+> **Changelog**: See bottom of document
+```
+
+---
+
+## Quick Copy Commands
+
+```bash
+# Create guidelines directory
+mkdir -p guidelines
+
+# Copy core files (adjust source path)
+cp ~/templates/projecthub/guidelines/AGENT_EDITING_INSTRUCTIONS.md guidelines/
+cp ~/templates/projecthub/guidelines/BRANCHING_STRATEGY.md guidelines/
+cp ~/templates/projecthub/guidelines/TESTING_STRATEGY.md guidelines/
+cp ~/templates/projecthub/.github/PULL_REQUEST_TEMPLATE.md .github/
+
+# Create fresh files
+touch guidelines/SINGLE_SOURCE_OF_TRUTH.md
+touch guidelines/LIBRARY_INVENTORY.md
+touch guidelines/DEPLOYMENT_STRATEGY.md
+```
+
+---
+
+## Related Documents
+
+- [AGENT_EDITING_INSTRUCTIONS.md](AGENT_EDITING_INSTRUCTIONS.md) - Core editing rules
+- [BRANCHING_STRATEGY.md](BRANCHING_STRATEGY.md) - Git workflow
+- [TESTING_STRATEGY.md](TESTING_STRATEGY.md) - Testing patterns
+- [SINGLE_SOURCE_OF_TRUTH.md](SINGLE_SOURCE_OF_TRUTH.md) - File locations
+- [LIBRARY_INVENTORY.md](LIBRARY_INVENTORY.md) - Dependencies
+- [DEPLOYMENT_STRATEGY.md](DEPLOYMENT_STRATEGY.md) - Deployment flow

package/templates/SCOPE_CREATION_WORKFLOW.md

@@ -0,0 +1,286 @@
+# Scope Creation Workflow for AI Agents
+
+This document provides a structured workflow for AI agents creating custom scope packages. **ALWAYS ASK before assuming** any details about the project.
+
+## Critical Rule: Zero-Assumption Principle
+
+**Never assume or infer details about:**
+- Project domain or industry
+- Feature areas or scope names
+- Naming conventions
+- Technical stack or architecture
+- Publishing intentions
+
+**Always prompt the user explicitly for this information.**
+
+---
+
+## Required Prompts (Ask in Order)
+
+### 1. Project Domain Clarification
+
+**Prompt:**
+> "What is the primary domain or industry for this project? For example: fintech, healthcare, gaming, education, e-commerce, etc."
+
+**Purpose:** Understand the context to suggest relevant scope categories.
+
+**Expected Response:** Single domain/industry name or brief description.
+
+---
+
+### 2. Feature Area Enumeration
+
+**Prompt:**
+> "What are the main feature areas or functional components of your project? Please list them (aim for 8-15 areas). For example, for a SaaS app: authentication, user profiles, billing, notifications, analytics."
+
+**Purpose:** Identify specific scopes that map to actual functionality.
+
+**Expected Response:** List of feature areas (comma-separated or numbered).
+
+**Follow-up:** If fewer than 8 or more than 20 features listed:
+> "You listed [N] features. The recommended range is 8-15 scopes. Would you like to add more detail, consolidate some areas, or proceed as is?"
+
+---
+
+### 3. Naming Convention Preferences
+
+**Prompt:**
+> "What naming style do you prefer for your scopes? Examples:
+> - Single words (auth, billing, users)
+> - Kebab-case (user-management, api-endpoints)
+> - Descriptive phrases (subscription-billing, email-notifications)
+> 
+> Note: All scope names must be lowercase alphanumeric with hyphens only."
+
+**Purpose:** Ensure consistent naming that matches team conventions.
+
+**Expected Response:** Preference indication or examples.
+
+---
+
+### 4. Scope-to-Structure Mapping
+
+**Prompt:**
+> "Do your scopes map to:
+> 1. **Folders/modules** in your codebase (e.g., src/auth, src/billing)
+> 2. **Feature areas** regardless of folder structure
+> 3. **Both** - they align with both features and folders
+> 
+> This helps determine how granular the scopes should be."
+
+**Purpose:** Align scopes with actual codebase organization.
+
+**Expected Response:** Choice of 1, 2, or 3.
+
+---
+
+### 5. Migration vs. New Creation
+
+**Prompt:**
+> "Are you:
+> 1. **Migrating** existing scopes from workflow.config.json to a package
+> 2. **Creating** a new custom scope package from scratch
+> 
+> If migrating, I can use your existing scope definitions. If creating new, we'll define them together."
+
+**Purpose:** Determine whether to use existing data or start fresh.
+
+**Expected Response:** "migrate" or "create new"
+
+**Follow-up if "migrate":**
+> "I found [N] scopes in your workflow.config.json:
+> [List scopes]
+> 
+> Should I use these as-is, or would you like to review/modify them first?"
+
+---
+
+### 6. Package Publishing Intent
+
+**Prompt:**
+> "Do you plan to:
+> 1. **Publish** this scope package to npm for reuse across projects
+> 2. **Keep it local** to this workspace only
+> 3. **Undecided** - create it now, decide later
+> 
+> This affects whether we include publishing configuration."
+
+**Purpose:** Include appropriate publishing metadata and instructions.
+
+**Expected Response:** Choice of 1, 2, or 3.
+
+---
+
+## Validation Checklist (Review Before Creating)
+
+Before generating the package, confirm:
+
+- [ ] All scope names are lowercase alphanumeric with hyphens
+- [ ] All scope names are 32 characters or less
+- [ ] No scope names match reserved words: init, create, build, test, config, docs, ci, deps
+- [ ] All scope descriptions are at least 10 characters
+- [ ] No duplicate scope names
+- [ ] Scope count is between 8-15 (or user explicitly accepted otherwise)
+- [ ] Package name is valid and doesn't conflict with existing packages
+
+---
+
+## Interactive Scope Definition (If Creating New)
+
+For each scope, ask:
+
+**Prompt:**
+> "Scope #[N] - Name: (lowercase, alphanumeric, hyphens only)"
+
+After name is provided:
+
+**Prompt:**
+> "Description for '[scope-name]': (minimum 10 characters, be specific)"
+
+After description:
+
+**Prompt:**
+> "Emoji for '[scope-name]': (optional, press Enter to skip)"
+
+After emoji:
+
+**Prompt:**
+> "Category for '[scope-name]':
+> 1. auth - Authentication & Authorization
+> 2. features - Features & Functionality
+> 3. infrastructure - Infrastructure & DevOps
+> 4. documentation - Documentation
+> 5. testing - Testing & QA
+> 6. performance - Performance & Optimization
+> 7. other - Other
+> 8. (none) - No category
+> 
+> Choose 1-8:"
+
+After each scope:
+
+**Prompt:**
+> "✓ Added scope: [scope-name]
+> 
+> You have [N] scopes. Add another? (y/n)"
+
+---
+
+## Example Interaction Flow
+
+```
+Agent: What is the primary domain or industry for this project?
+User: Healthcare SaaS platform
+
+Agent: What are the main feature areas of your healthcare SaaS? 
+      (aim for 8-15 areas)
+User: patient records, appointments, billing, insurance, 
+      prescriptions, lab results, messaging, reports
+
+Agent: What naming style do you prefer?
+      1. Single words (patients, billing)
+      2. Kebab-case (patient-records, lab-results)
+      3. Descriptive (patient-record-management)
+User: Option 2, kebab-case
+
+Agent: Do your scopes map to folders, features, or both?
+User: Both - they match our src/ folder structure
+
+Agent: Are you migrating existing scopes or creating new?
+User: Creating new
+
+Agent: Scope #1 - Name:
+User: patient-records
+
+Agent: Description for 'patient-records':
+User: Patient medical records and history management
+
+Agent: Emoji for 'patient-records': (optional)
+User: 📋
+
+Agent: Category for 'patient-records':
+User: 2 (features)
+
+Agent: ✓ Added scope: patient-records
+      You have 1 scope. Add another? (y/n)
+User: y
+
+[Continue for remaining scopes...]
+```
+
+---
+
+## Error Handling
+
+If user provides invalid input:
+
+**For invalid scope name:**
+> "The name '[name]' is invalid. Scope names must be:
+> - Lowercase letters, numbers, and hyphens only
+> - Maximum 32 characters
+> - Not a reserved word (init, create, build, test, config, docs, ci, deps)
+> 
+> Please provide a different name:"
+
+**For short description:**
+> "The description must be at least 10 characters to be meaningful. 
+> Please provide more detail about what '[scope-name]' covers:"
+
+**For duplicate name:**
+> "A scope named '[name]' already exists. Please choose a different name:"
+
+---
+
+## Post-Creation Instructions
+
+After successfully creating the package, provide:
+
+1. **Location confirmation:**
+   > "✨ Custom scope package created at: [path]"
+
+2. **Next steps:**
+   > "Next steps:
+   > 1. cd [path]
+   > 2. pnpm install
+   > 3. pnpm build
+   > 4. pnpm test
+   > 5. Update repository URL in package.json"
+
+3. **Publishing instructions** (if user indicated intent):
+   > "To publish to npm:
+   > 1. npm login
+   > 2. Update version in package.json as needed
+   > 3. pnpm publish --access public"
+
+4. **Usage instructions:**
+   > "To use in other projects:
+   > pnpm add @workflow/scopes-[name]"
+
+---
+
+## Summary: Key Principles
+
+1. ✅ **Always ask** - never assume project details
+2. ✅ **Validate input** - check all constraints before proceeding
+3. ✅ **Provide examples** - show users what good input looks like
+4. ✅ **Confirm before creating** - review all scopes with user
+5. ✅ **Give clear next steps** - don't leave users wondering what to do next
+
+---
+
+## Automation Support
+
+For non-interactive/CI environments, support these flags:
+
+```bash
+workflow scope:create \
+  --name fintech \
+  --preset-name "FinTech Application" \
+  --scopes "auth:Authentication and security:🔐:auth,payments:Payment processing:💳:features,accounts:Account management:👤:features"
+```
+
+Format: `name:description:emoji:category` (comma-separated)
+
+---
+
+**Remember: The goal is to create scopes that genuinely reflect the user's project structure and workflow. Taking time to ask the right questions upfront leads to better, more useful scope packages.**