@nakedved/ano

# Team Configuration This guide covers setting up team-based approvals and role requirements in Ano. ## Overview Ano supports team-based workflows where: - Team members are tracked with roles - Approvals can require specific roles or titles - Role weights can be used for weighted approval thresholds ## Quick Start ```bash # Initialize team config ano team init "My Project" # Add team members ano team add alice@example.com --name "Alice" --role lead ano team add bob@example.com --name "Bob" --role reviewer # List team ano team list ``` ## Configuration File Team config is stored in `.ano/config.json`: ```json { "version": "1.0", "projectName": "My Project", "members": [ { "name": "Alice", "email": "alice@example.com", "role": "lead" }, { "name": "Bob", "email": "bob@example.com", "role": "reviewer" } ], "roles": { "lead": { "canOverride": true, "weight": 2 }, "reviewer": { "canOverride": false, "weight": 1 } }, "requirements": { "minApprovals": 2, "requiredRoles": ["lead"], "requiredTitles": [] } } ``` ## Team Commands ### Initialize Team ```bash ano team init [project-name] ``` Creates `.ano/config.json` with default settings. ### Add Member ```bash ano team add <email> [options] Options: --name <name> Display name --role <role> Role (lead, reviewer, or custom) ``` Examples: ```bash ano team add alice@example.com --name "Alice Smith" --role lead ano team add bob@example.com --role reviewer ``` ### Remove Member ```bash ano team remove <email> ``` ### List Team ```bash ano team list ``` Shows all members with their roles. ### Show Roles ```bash ano team roles ``` Lists available roles and their permissions. ## Roles ### Built-in Roles | Role | Weight | Can Override | |------|--------|--------------| | `lead` | 2 | Yes | | `reviewer` | 1 | No | ### Custom Roles Add custom roles in `.ano/config.json`: ```json { "roles": { "lead": { "canOverride": true, "weight": 2 }, "reviewer": { "canOverride": false, "weight": 1 }, "security": { "canOverride": true, "weight": 3 }, "junior": { "canOverride": false, "weight": 0.5 } } } ``` ### Role Weights Weights are used with `minWeight` requirement: ```json { "requirements": { "minWeight": 3 } } ``` - Lead (weight 2) + Reviewer (weight 1) = 3 (passes) - Two Reviewers (weight 1 each) = 2 (fails) ## Requirements Configure approval requirements in `.ano/config.json`: ### Minimum Approvals ```json { "requirements": { "minApprovals": 2 } } ``` Requires at least 2 approvals from any team member. ### Required Roles ```json { "requirements": { "requiredRoles": ["lead", "security"] } } ``` Requires at least one approval from each specified role. ### Required Titles ```json { "requirements": { "requiredTitles": ["Tech Lead", "Security Review"] } } ``` Requires approvals with specific titles: ```bash ano approve plan.md --title "Tech Lead" ano approve plan.md --title "Security Review" ``` ### Minimum Weight ```json { "requirements": { "minWeight": 4 } } ``` Requires total approval weight to meet threshold. ### Combined Requirements All requirements must be met: ```json { "requirements": { "minApprovals": 2, "requiredRoles": ["lead"], "requiredTitles": ["Security Review"], "minWeight": 3 } } ``` ## CLI Check Options Override config requirements via CLI: ```bash # Require specific number of approvals ano check plan.md --required 3 # Require specific role ano check plan.md --require-role lead # Require specific title ano check plan.md --require-title "Tech Lead" # Combine requirements ano check plan.md --required 2 --require-role lead --require-title "Security" ``` ## Approval Workflow ### 1. View Requirements ```bash ano team list ``` Shows: ``` Team: My Project Members: Alice <alice@example.com> [lead] Bob <bob@example.com> [reviewer] Requirements: Min approvals: 2 Required roles: lead ``` ### 2. Check Current Status ```bash ano check plan.md ``` Shows: ``` Approval Status: plan.md Approvals: 1/2 required - Alice <alice@example.com> [lead] - approved Missing: - 1 more approval needed - Role 'lead' requirement met Result: NOT APPROVED ``` ### 3. Approve with Title ```bash ano approve plan.md --title "Tech Lead" ``` ### 4. Override (if allowed) ```bash ano check plan.md --override --reason "Emergency fix" ``` Only users with `canOverride: true` roles can override. ## Team Membership ### Advisory Nature Team membership is **advisory** - anyone can approve, but: - `ano check` shows who is/isn't in the team - Role requirements only count team member approvals - Non-members show as "external" in status ### Example Output ```bash ano check plan.md ``` ``` Approvals: - Alice <alice@example.com> [lead] (team member) - Charlie <charlie@other.com> (external) Note: External approval from charlie@other.com ``` ## Hook Integration Use team config with hooks: ```json { "hooks": { "PreToolUse": [ { "matcher": "Write", "command": "ano check PLAN.md --quiet" } ] } } ``` The hook uses requirements from `.ano/config.json` automatically. Override via CLI flags if needed: ```json { "command": "ano check PLAN.md --required 3 --require-role security --quiet" } ``` ## Best Practices ### 1. Start Simple Begin with basic requirements: ```json { "requirements": { "minApprovals": 1 } } ``` Add complexity as needed. ### 2. Use Roles for Expertise Assign roles based on expertise: - `security` - Security team members - `backend` - Backend developers - `frontend` - Frontend developers - `devops` - DevOps engineers ### 3. Use Titles for Context Use titles for situational approvals: - "Tech Lead" - Overall technical sign-off - "Security Review" - Security audit complete - "Performance Review" - Performance validated ### 4. Document Requirements Keep a README in `.ano/` explaining: - What each role means - When each title should be used - Override policy ## Troubleshooting ### "Role not found" Ensure the role exists in `config.json`: ```json { "roles": { "custom-role": { "canOverride": false, "weight": 1 } } } ``` ### "External approval" warnings The approver's email doesn't match any team member. Either: - Add them to the team - Ignore if external approvals are acceptable ### Requirements not loading Check that `.ano/config.json` exists and is valid JSON: ```bash cat .ano/config.json | jq . ``` ## Next Steps - [Claude Integration](./claude-integration.md) - Set up MCP and hooks - [Web Viewer Guide](./web-viewer.md) - Learn all web UI features