# zeoel-team Step-by-Step Process This guide explains how to start `zeoel-team`, choose the AI CLI/model, run each workflow command, approve phase gates, and know which files to review after every step. Install globally: ```bash npm install -g zeoel-team ``` For local development from this checkout: ```bash npm install -g . ``` Run all commands from the client workspace folder where you want `projects/` and `zeoel-team.config.json` to live: ```bash cd /path/to/client-workspace ``` ## 1. Validate The Framework Run: ```bash zeoel-team validate-framework ``` Review: - Required framework folders are present. - Resource paths are resolved. - The npm package includes lightweight bundled resource folders. - If full resource repositories are stored outside the npm package, set `ZEOEL_TEAM_RESOURCES_DIR=/path/to/resources`. ## 2. Choose The AI CLI List supported execution targets: ```bash zeoel-team list-engines ``` Scan the installed assistant CLIs and fetch model lists when the tool exposes them: ```bash zeoel-team list-engines --scan ``` Supported CLI IDs: - `codex` - `claude-code` - `cursor` - `gemini-cli` - `github-copilot` - `antigravity` - `opencode` - `qwen` - `mimo` - `custom` The model value is a string. Use the model name your selected tool supports. Save the default CLI/model for future projects: ```bash zeoel-team configure-default-engine ``` Or set it directly: ```bash zeoel-team configure-default-engine --cli opencode --model deepseek-4-pro ``` Check the saved default: ```bash zeoel-team default-engine-status ``` ## 2.1 Optional Full Resources The npm package includes lightweight bundled resource folders. To install the full GitHub resources locally: ```bash zeoel-team resources install --all ``` Review active resource paths: ```bash zeoel-team resources status ``` By default, full resources install to `~/.zeoel-team/resources` and are reused from any client workspace. You can choose a different location: ```bash zeoel-team resources install --all --dir ./resources export ZEOEL_TEAM_RESOURCES_DIR="$PWD/resources" ``` ## 3. Initialize A Client Project Run: ```bash zeoel-team init --name "Client Portal" ``` `init` uses the saved default CLI/model when `--cli` and `--model` are omitted. Explicit flags still override the saved default for that project: ```bash zeoel-team init --name "Client Portal" --cli claude-code --model sonnet ``` This creates: ```txt projects/client-portal/ ├── idea.md ├── project.config.yml ├── state.json ├── approvals/ ├── company/ ├── assets/ ├── docs/ ├── generated/ ├── versions/ └── logs/ ``` Review: - `projects/client-portal/idea.md` - `projects/client-portal/project.config.yml` - `projects/client-portal/state.json` - `projects/client-portal/approvals/` ## 4. Check Or Change The Active CLI/Model Check current engine: ```bash zeoel-team engine-status --project client-portal ``` Change anytime: ```bash zeoel-team set-engine --project client-portal --cli gemini-cli --model default ``` Alias: ```bash zeoel-team configure-engine --project client-portal --cli cursor --model default ``` This updates: - `projects/client-portal/project.config.yml` - `projects/client-portal/state.json` - `projects/client-portal/logs/audit.log` ## 5. Fill The Client Idea Open: ```txt projects/client-portal/idea.md ``` Add: - Project name - Business problem - Client goals - Target users - Main features - Competitors or references - Budget - Timeline - Preferred technology - Brand/logo/assets - Color and design references - Integrations - Admin requirements - User roles - Payment requirements - Security requirements - Reporting needs - Mobile/web needs - Deployment expectations - Maintenance expectations ## 6. Run Discovery Analysis Run: ```bash zeoel-team analyze-idea --project client-portal ``` This generates: - `docs/01-discovery/enhanced_idea.md` - `docs/01-discovery/questionnaire.md` - `docs/01-discovery/questionnaire-answers.md` - `docs/01-discovery/research-report.md` - `docs/01-discovery/project_brief.md` Review before approval: - Is the business problem clear? - Are target users clear? - Are scope boundaries clear? - Are assumptions and open questions documented? - Are brand/logo/assets status and integrations clear? Optional brainstorm: ```bash zeoel-team brainstorm --project client-portal ``` Review: - `docs/01-discovery/brainstorm.md` ## 7. Approve Discovery Run: ```bash zeoel-team approve-phase --project client-portal --phase discovery --decision approved --approver "Client Name" ``` Other allowed decisions: - `approved` - `approved_with_minor_changes` - `needs_revision` - `rejected` If discovery is not approved, proposal generation is blocked. ## 8. Generate Proposal Run: ```bash zeoel-team generate-proposal --project client-portal ``` This generates: - `docs/02-proposal/project_proposal.md` - `docs/02-proposal/scope-table.md` - `docs/02-proposal/estimation.md` - `docs/02-proposal/project_proposal.pdf-generation.md` when PDF generation is not configured - `docs/02-proposal/proposal-presentation/` - `versions/proposal/project_proposal-v1.md` Review: - Scope of work - Feature list - Estimation - Assumptions - Exclusions - Change request policy - Client responsibilities - Legal disclaimer Approve proposal: ```bash zeoel-team approve-phase --project client-portal --phase proposal --decision approved --approver "Client Name" ``` If proposal is not approved, contract generation is blocked. ## 9. Generate Contract Draft Run: ```bash zeoel-team generate-contract --project client-portal ``` This generates: - `docs/03-contract/contract.md` - `docs/03-contract/payment-schedule.md` - `docs/03-contract/kickoff-notes.md` - `docs/03-contract/contract.pdf-generation.md` when PDF generation is not configured - `versions/contract/contract-v1.md` Important: The contract is an AI-generated draft. It is not legal advice. Final legal documents must be reviewed by a qualified legal professional. Approve contract: ```bash zeoel-team approve-phase --project client-portal --phase contract --decision approved --approver "Client Name" ``` If contract is not approved, planning is blocked. ## 10. Generate Product Plan, UX, And Architecture Run: ```bash zeoel-team generate-plan --project client-portal ``` This generates: - `docs/04-planning/plan.md` - `docs/04-planning/plan-v1.md` - `docs/04-planning/prd.md` - `docs/04-planning/user-stories.md` - `docs/04-planning/acceptance-criteria.md` - `docs/04-planning/ui-ux-plan.md` - `docs/04-planning/architecture.md` - `docs/04-planning/database-erd.md` - `docs/04-planning/api-spec.md` - `docs/04-planning/security-plan.md` - `docs/04-planning/third-party-integrations.md` - `docs/04-planning/planning-presentation/` - `versions/plan/plan-v1.md` Review: - Product requirements - User stories - Acceptance criteria - UI/UX plan - Architecture - API and ERD planning - Security plan - Integration plan Approve planning: ```bash zeoel-team approve-phase --project client-portal --phase planning --decision approved --approver "Client Name" ``` If planning is not approved, sprint planning is blocked. ## 11. Generate Sprint Plans Run: ```bash zeoel-team generate-sprints --project client-portal --count 2 ``` This generates: - `docs/05-sprints/sprint-master-plan.md` - `docs/05-sprints/sprint-001/sprint-plan.md` - `docs/05-sprints/sprint-001/tasks.md` - `docs/05-sprints/sprint-001/subtasks.md` - `docs/05-sprints/sprint-001/acceptance.md` - `docs/05-sprints/sprint-001/definition-of-done.md` - `docs/05-sprints/sprint-001/sprint-review.md` - More sprint folders depending on `--count` Review: - Every task has a task ID. - Every task has an owner. - Every task has acceptance criteria. - Every task has testing requirements. - Every task has security checks. - Dependencies are clear. Approve sprint planning: ```bash zeoel-team approve-phase --project client-portal --phase sprint_planning --decision approved --approver "Client Name" ``` If sprint planning is not approved, development is blocked. ## 12. Run A Sprint Run: ```bash zeoel-team run-sprint --project client-portal --sprint 1 ``` This generates or updates: - `docs/06-development/development-log.md` - `docs/06-development/code-review-log.md` - `docs/06-development/technical-decisions.md` Important: This currently records and structures the development workflow. Live execution through Claude Code, Cursor, Gemini CLI, Copilot, Antigravity, or Codex requires future execution adapters. Approve development when the sprint work is ready for QA: ```bash zeoel-team approve-phase --project client-portal --phase development --decision approved --approver "Technical Lead" ``` ## 13. Run QA And Security Audit Run clean QA: ```bash zeoel-team audit-quality --project client-portal --critical 0 --high 0 ``` Run QA with blockers: ```bash zeoel-team audit-quality --project client-portal --critical 1 --high 0 ``` This generates: - `docs/07-qa-security/qa-report.md` - `docs/07-qa-security/test-plan.md` - `docs/07-qa-security/unit-test-report.md` - `docs/07-qa-security/integration-test-report.md` - `docs/07-qa-security/security-audit-report.md` - `docs/07-qa-security/performance-report.md` - `docs/07-qa-security/bugfix-sprint-plan.md` when critical/high issues exist Release is blocked until: - Critical bugs = 0 - High bugs = 0, unless explicitly accepted - QA report exists - Security audit report exists Approve QA/security only when acceptable: ```bash zeoel-team approve-phase --project client-portal --phase qa_security --decision approved --approver "QA Lead" ``` ## 14. Generate Release Package Run: ```bash zeoel-team release-production --project client-portal ``` This generates: - `docs/08-release/release-plan.md` - `docs/08-release/deployment-checklist.md` - `docs/08-release/release-notes.md` - `docs/08-release/rollback-plan.md` - `docs/08-release/production-signoff.md` Review: - QA approved - Security approved - Environment variables reviewed - Database migration plan reviewed - Backup confirmed - Rollback plan exists - Client/company signoff exists Approve release: ```bash zeoel-team approve-phase --project client-portal --phase release --decision approved --approver "Client Name" ``` ## 15. Generate Support And Maintenance Docs Run: ```bash zeoel-team monitor-support --project client-portal ``` This generates: - `docs/09-support/maintenance-plan.md` - `docs/09-support/monitoring-plan.md` - `docs/09-support/incident-response-plan.md` - `docs/09-support/support-sla.md` Review: - Monitoring tools - Error tracking - Uptime checks - Backup schedule - Security patching - Bug fix policy - SLA levels - Incident response times - Monthly maintenance tasks ## 16. Create A Change Request Run: ```bash zeoel-team create-change-request --project client-portal --title "Add mobile app" ``` This generates: - `docs/10-change-requests/change-request-001.md` - `docs/10-change-requests/version-2-plan.md` Review: - Requested change - Business value - Affected modules - Impact on timeline - Impact on cost - Impact on architecture - Impact on testing - Security impact - Approval status Approve the change request before adding it to active development: ```bash zeoel-team approve-phase --project client-portal --phase change_request --decision approved --approver "Client Name" ``` ## 17. Audit Gates Anytime Run: ```bash zeoel-team audit-gates --project client-portal ``` Use this to see which phases pass or fail their quality gates. ## Full Happy-Path Command Sequence ```bash zeoel-team list-engines zeoel-team configure-default-engine zeoel-team init --name "Client Portal" zeoel-team engine-status --project client-portal zeoel-team analyze-idea --project client-portal zeoel-team approve-phase --project client-portal --phase discovery --decision approved --approver "Client" zeoel-team generate-proposal --project client-portal zeoel-team approve-phase --project client-portal --phase proposal --decision approved --approver "Client" zeoel-team generate-contract --project client-portal zeoel-team approve-phase --project client-portal --phase contract --decision approved --approver "Client" zeoel-team generate-plan --project client-portal zeoel-team approve-phase --project client-portal --phase planning --decision approved --approver "Client" zeoel-team generate-sprints --project client-portal --count 2 zeoel-team approve-phase --project client-portal --phase sprint_planning --decision approved --approver "Client" zeoel-team run-sprint --project client-portal --sprint 1 zeoel-team audit-quality --project client-portal --critical 0 --high 0 zeoel-team approve-phase --project client-portal --phase qa_security --decision approved --approver "QA Lead" zeoel-team release-production --project client-portal zeoel-team approve-phase --project client-portal --phase release --decision approved --approver "Client" zeoel-team monitor-support --project client-portal zeoel-team create-change-request --project client-portal --title "Add mobile app" ``` ## Common Blocking Messages `Approval required before proposal` Discovery approval is missing. Review discovery docs, then approve discovery. `Approval required before contract` Proposal approval is missing. Review proposal docs, then approve proposal. `Approval required before planning` Contract approval is missing. Review contract draft and kickoff docs, then approve contract. `Quality gate failed for "qa_security"` QA/security reports have critical or high bugs. Fix issues or document accepted high-risk exception. ## Practical Operating Rule At every phase: 1. Run the command. 2. Review generated documents. 3. Answer open questions or mark assumptions. 4. Approve the phase only when acceptable. 5. Move to the next command. Do not skip approval gates. The framework is designed to protect scope, quality, budget, security, and client expectations.