Tasks 1-2 Detailed Execution Plan¶
This document expands the first two roadmap tasks into execution-ready features with detailed task decomposition.
Source scope: - Task 1: Project Bootstrap and Team Operating Model - Task 2: Development Environment and Monorepo Scaffolding
Feature 1: Project Bootstrap and Team Operating Model¶
Feature outcome: - The repository has a clear contribution system, repeatable planning cadence, a frozen 90-day MVP scope, and documented architecture decisions.
Task 1.1: Create Repository Standards¶
Task outcome: - Contributors can open consistent issues and pull requests, and maintainers can evaluate work against an explicit quality bar.
Subtask 1.1.1: Define Branching and Pull Request Governance¶
Atomic actions and changes: - Create main protection rules: - Require pull request before merge. - Require at least one approval. - Require status checks to pass. - Disallow force pushes and branch deletion. - Define branch naming conventions: - feature/<area>-<short-name> - fix/<area>-<short-name> - chore/<area>-<short-name> - Define commit conventions: - Use semantic prefixes: feat, fix, docs, chore, refactor, test. - Enforce signed commits where practical. - Add merge policy: - Squash merge default. - PR title becomes final commit message.
Subtask 1.1.2: Standardize Issue Templates¶
Atomic actions and changes: - Create issue forms under .github/ISSUE_TEMPLATE/: - bug-report.yml - feature-request.yml - task.yml - Include required fields: - Problem statement. - Expected outcome. - Scope and non-goals. - Acceptance criteria. - Test strategy. - Add labels automation in templates: - type:bug, type:feature, type:task. - priority:* and area:* labels.
Subtask 1.1.3: Standardize Pull Request Template¶
Atomic actions and changes: - Create .github/pull_request_template.md. - Include mandatory sections: - Summary of change. - Linked issue(s). - Risk and rollback notes. - Test evidence. - Documentation updates. - Add checklist: - Lint passes. - Tests added or updated. - Backward compatibility reviewed. - Security impact reviewed.
Subtask 1.1.4: Define Labels and Workflow Taxonomy¶
Atomic actions and changes: - Create label groups: - Type labels: type:feature, type:bug, type:task, type:docs. - Area labels: area:core, area:cli, area:sdk-python, area:docs, area:devops. - Priority labels: priority:p0, priority:p1, priority:p2. - Status labels: status:blocked, status:ready, status:in-progress. - Define milestone structure: - M1 Foundations - M2 Build and Integrate - M3 Stabilize and Beta - Add issue lifecycle rules: - Every issue must have exactly one type:*. - Every issue must have exactly one priority:*. - Every issue must map to one milestone.
Subtask 1.1.5: Formalize Definition of Done¶
Atomic actions and changes: - Write a shared Definition of Done section in CONTRIBUTING.md (or create if absent). - Require completion gates: - Acceptance criteria met. - Code reviewed and approved. - Tests pass in CI. - Docs updated where relevant. - Security considerations reviewed. - Add release readiness criteria for merge to main: - No unresolved blocker comments. - No failing required checks.
Task 1.2: Set Up Delivery Rhythm¶
Task outcome: - The team executes a predictable weekly operating cadence with clear ownership and review loops.
Subtask 1.2.1: Define Weekly Cadence¶
Atomic actions and changes: - Establish recurring events: - Weekly planning (60 minutes). - Mid-week checkpoint (30 minutes). - End-of-week demo and retro (60 minutes). - Define fixed agenda templates for each meeting type. - Publish cadence and timezone expectations in docs/ process notes.
Subtask 1.2.2: Introduce Work-in-Progress and Capacity Rules¶
Atomic actions and changes: - Set WIP limits: - Max 1 active issue per owner in "in-progress". - Max 3 active issues per area for maintainability. - Define planned capacity per week: - Feature work. - Bug fixing. - Technical debt and docs. - Add blocked-work protocol: - Blocker tagged within 24 hours. - Escalation owner assigned.
Subtask 1.2.3: Establish Ownership Model¶
Atomic actions and changes: - Define ownership matrix by area: - Core engine owner. - CLI owner. - SDK owner. - Docs and DX owner. - CI and infrastructure owner. - Require every issue to include: - Directly responsible individual (DRI). - Reviewer. - Target completion week.
Subtask 1.2.4: Define Reporting and Tracking¶
Atomic actions and changes: - Track weekly delivery metrics: - Planned vs completed issues. - Lead time and cycle time. - Escaped defects. - Time-to-first-review. - Add a weekly status note template: - Wins. - Risks. - Blockers. - Next-week commitments.
Task 1.3: Define and Freeze 90-Day MVP Boundaries¶
Task outcome: - Team alignment on what is in scope now and deferred to later phases.
Subtask 1.3.1: Define In-Scope Deliverables¶
Atomic actions and changes: - Include in-scope capabilities: - Go core risk assessment pipeline. - CLI scan and assess commands. - Python SDK minimal assess methods. - Evidence JSON output. - Core onboarding docs. - Define minimum quality targets: - Basic automated tests in each package. - CI build + lint checks. - Security baseline checks.
Subtask 1.3.2: Define Explicit Non-Goals¶
Atomic actions and changes: - Mark out-of-scope for this 90-day window: - Full enterprise RBAC and SSO. - Full dashboard analytics suite. - Multi-framework compliance beyond initial EU AI Act set. - Advanced billing and monetization workflows. - Document rationale for each non-goal to reduce scope creep.
Subtask 1.3.3: Define Acceptance Criteria Per Stream¶
Atomic actions and changes: - Core stream acceptance: - Deterministic risk outputs for baseline test fixtures. - CLI stream acceptance: - Stable exit codes and JSON output contract. - SDK stream acceptance: - Typed response objects and passing tests. - Docs stream acceptance: - Time-to-first-scan path under 15 minutes.
Subtask 1.3.4: Introduce Change Control for Scope¶
Atomic actions and changes: - Add scope change template: - Proposed change. - Value and risk. - Cost estimate. - Impacted milestones. - Require approval from product and technical owners before expanding scope.
Task 1.4: Create Architecture Decision Records (ADRs)¶
Task outcome: - Important technical decisions are traceable, reviewable, and maintainable over time.
Subtask 1.4.1: Create ADR Structure¶
Atomic actions and changes: - Create ADR directory: - docs/adr/ - Add ADR template: - Context. - Decision. - Alternatives considered. - Consequences. - Status (proposed/accepted/superseded).
Subtask 1.4.2: Record Initial Foundational Decisions¶
Atomic actions and changes: - ADR: Go for core and CLI. - ADR: Python-first SDK priority. - ADR: docs-first growth motion and MDX docs. - ADR: project structure and package boundaries. - ADR: CI quality gates and release policy.
Subtask 1.4.3: Integrate ADRs into Engineering Workflow¶
Atomic actions and changes: - Require ADR reference in PRs introducing major design changes. - Add ADR review checklist in PR template. - Add periodic ADR review cadence every 4 weeks.
Feature 2: Development Environment and Monorepo Scaffolding¶
Feature outcome: - A contributor can set up the repository quickly, run all basic checks locally, and work against a clear multi-package structure.
Task 2.1: Set Up Language Toolchains¶
Task outcome: - Local and CI environments are consistent across Go, Node.js, Python, and Docker workflows.
Subtask 2.1.1: Define Version and Tooling Policy¶
Atomic actions and changes: - Pin versions: - Go 1.22+ - Node.js 20+ - Python 3.11+ - pnpm latest stable - Document version policy in root setup guide. - Add compatibility notes for Windows, macOS, and Linux.
Subtask 2.1.2: Configure Go Tooling¶
Atomic actions and changes: - Install and verify: - go version - gofmt - go test - Add golangci-lint setup guidance. - Define standard commands: - lint command. - unit test command. - integration test command.
Subtask 2.1.3: Configure Node.js Tooling¶
Atomic actions and changes: - Install and verify: - node -v - pnpm -v - Define workspace script conventions: - lint, test, build, dev. - Configure editor support: - ESLint. - TypeScript.
Subtask 2.1.4: Configure Python Tooling¶
Atomic actions and changes: - Choose dependency manager (uv or poetry) and document standard. - Define virtual environment setup and activation flow. - Configure lint/format/test tools: - ruff. - black. - pytest. - Add package installation and editable mode instructions.
Subtask 2.1.5: Configure Docker Tooling¶
Atomic actions and changes: - Verify Docker Desktop installation. - Define local container usage conventions: - Service names. - Port mapping. - Environment variable injection. - Provide baseline compose file strategy for local dependencies.
Task 2.2: Initialize Monorepo Layout¶
Task outcome: - The repository has clear package boundaries and can scale to the planned architecture.
Subtask 2.2.1: Create Directory Structure¶
Atomic actions and changes: - Create package directories: - packages/core - packages/cli - packages/sdk-python - packages/api (placeholder, if needed) - packages/dashboard (placeholder, if needed) - Keep docs in docs/ and examples in examples/. - Add README per package with purpose, commands, and ownership.
Subtask 2.2.2: Scaffold Package Manifests and Entry Points¶
Atomic actions and changes: - Core: - Initialize go.mod. - Add base package and test files. - CLI: - Initialize go.mod. - Add command root and command placeholders. - SDK Python: - Add pyproject.toml. - Add src/ package skeleton. - Add tests/ skeleton. - Docs: - Ensure doc tooling config and scripts are ready.
Subtask 2.2.3: Define Shared Conventions Across Packages¶
Atomic actions and changes: - Define naming and module conventions. - Define folder-level ownership and review rules. - Define package versioning strategy. - Add dependency boundaries to avoid circular coupling.
Task 2.3: Configure Shared Tooling¶
Task outcome: - Quality, formatting, and commit policies are consistently enforced.
Subtask 2.3.1: Set Up Formatting and Linting Pipelines¶
Atomic actions and changes: - Configure language-specific linters and formatters. - Add root scripts or make targets to run all checks. - Ensure deterministic outputs and stable lint rules.
Subtask 2.3.2: Add Pre-Commit and Commit Hooks¶
Atomic actions and changes: - Configure hooks for: - Changed-file formatting. - Basic lint checks. - Secret scan pre-check (lightweight). - Keep hook execution time low to maintain developer flow.
Subtask 2.3.3: Add Commit Signing and Security Hygiene Guidance¶
Atomic actions and changes: - Document GPG setup and verification. - Add no-secrets policy with examples. - Add secure environment variable handling instructions.
Task 2.4: Create Onboarding Scripts and Setup Automation¶
Task outcome: - New contributors can get a working environment with minimal manual effort.
Subtask 2.4.1: Build Bootstrap Scripts¶
Atomic actions and changes: - Create cross-platform setup scripts: - scripts/bootstrap.ps1 - scripts/bootstrap.sh - Include: - Dependency checks. - Package installs. - Hook setup. - Basic sanity checks.
Subtask 2.4.2: Add Verification Script¶
Atomic actions and changes: - Create a scripts/doctor command that validates: - Tool versions. - Required binaries in PATH. - Repo dependency install state. - Local test and lint command availability.
Subtask 2.4.3: Add First-Day Contributor Path¶
Atomic actions and changes: - Create one "first hour" onboarding checklist: - Setup complete. - Run lint and tests. - Build CLI. - Run sample assessment. - Submit first docs-only PR. - Add troubleshooting matrix: - Common errors. - Probable causes. - Direct fix commands.
Suggested Execution Sequence (First 2 Weeks)¶
- Week 1:
- Complete Feature 1 Task 1.1 and 1.3.
- Start Feature 2 Task 2.1 and 2.2.
- Week 2:
- Complete Feature 1 Task 1.2 and 1.4.
- Complete Feature 2 Task 2.3 and 2.4.
Definition of Completion for Tasks 1-2¶
- Every subtask has a visible artifact in the repository or docs.
- Every task has at least one owner and target week.
- Setup from zero to first local run is reproducible on a clean machine.
- Scope boundaries and ADRs are documented and referenced by active issues.