{"id":51882249,"url":"https://github.com/datashaman/growth","last_synced_at":"2026-07-25T14:30:43.623Z","repository":{"id":359282955,"uuid":"1236394842","full_name":"datashaman/growth","owner":"datashaman","description":"Engineering-process workbench and MCP server for AI-assisted software projects","archived":false,"fork":false,"pushed_at":"2026-05-29T15:34:30.000Z","size":2472,"stargazers_count":1,"open_issues_count":5,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T17:15:48.602Z","etag":null,"topics":["ai-agents","github-actions","governance","laravel","mcp","project-management","readiness","requirements","software-engineering","traceability"],"latest_commit_sha":null,"homepage":null,"language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/datashaman.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-12T07:55:00.000Z","updated_at":"2026-05-29T15:34:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/datashaman/growth","commit_stats":null,"previous_names":["datashaman/growth"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/datashaman/growth","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datashaman%2Fgrowth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datashaman%2Fgrowth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datashaman%2Fgrowth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datashaman%2Fgrowth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/datashaman","download_url":"https://codeload.github.com/datashaman/growth/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/datashaman%2Fgrowth/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35883105,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-25T02:00:06.922Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","github-actions","governance","laravel","mcp","project-management","readiness","requirements","software-engineering","traceability"],"created_at":"2026-07-25T14:30:42.820Z","updated_at":"2026-07-25T14:30:43.614Z","avatar_url":"https://github.com/datashaman.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Growth\n\nGrowth is an engineering-process workbench for teams using client-side AI coding agents. It combines a Laravel web app, an MCP server surface, and a shared project database so agents and humans can work against the same project model.\n\nGrowth does not host or run an agent. Claude Code, Cursor, claude.ai, or another MCP host remains the client agent. Growth serves tools, resources, prompts, dashboards, and role context; records the work those clients perform; and keeps the product intent, plan, evidence, and governance trail coherent.\n\n## What Growth Tracks\n\nGrowth models a software project from intent through delivery:\n\n- product intent, stakeholders, concerns, sources, citations, and requirements\n- architecture viewpoints, views, elements, and traceability\n- verification plans, cases, runs, anomalies, and evidence assets\n- project plans, milestones, roles, agents, RACI assignments, work items, dependencies, risks, releases, and deployments\n- spec mockups for work items and UI requirements, including named alternatives and coverage gaps\n- reviews, findings, decision events, change requests, impact analysis, and approval history\n- decision requests, notifications, feedback, and recorded MCP tool activity\n- GitHub delivery evidence from pull requests, checks, deployments, and releases\n\nThe web app gives humans a project dashboard and artifact pages. The MCP surfaces expose the same model to trusted local and HTTP clients.\n\n## Product Surfaces\n\nThe authenticated web app includes:\n\n- dashboard\n- intent\n- requirements\n- architecture\n- verification\n- plan\n- mockups\n- evidence\n- changes\n- reviews\n- roles\n- feedback\n- notifications\n- tool invocations\n\nThe MCP app resources include read-only project dashboards, gate status, trace graphs, and requirement exploration views that can be rendered by compatible MCP clients. The data resources include project index, canonical project documents, manifests and manifest sections, playbooks, rigor levels, artifact briefs, mockups, and evidence/readiness resources.\n\n## Local Development\n\nRequirements:\n\n- PHP 8.4+\n- Composer\n- Node.js and npm\n- SQLite for the default local database\n- Redis if you want Horizon/Reverb-style local worker behavior\n\nSet up the app:\n\n```bash\ncomposer setup\nphp artisan db:seed\n```\n\nRun the full local development stack:\n\n```bash\ncomposer dev\n```\n\nThat starts the Laravel server, Vite, Reverb, Horizon listener, and log tailing process defined in `composer.json`.\n\nRun tests:\n\n```bash\ncomposer test\nnpm run test:sync\n```\n\nThe default seeder creates demo users and demo projects. Local seeded users use the password `password`.\n\n## Local MCP Users\n\nCreate a local user, then run a trusted stdio MCP capability-surface server as that user:\n\n```bash\nphp artisan user:create user@example.com --name=\"Example User\"\nGROWTH_USER_EMAIL='user@example.com' php artisan mcp:start all\n```\n\n`GROWTH_USER_ID` is also supported. `GROWTH_WORKSPACE_ID` can override the user's active workspace for local stdio MCP. HTTP MCP clients and GitHub sync use Passport bearer tokens instead.\n\nAvailable MCP capability-surface handles:\n\n- `all` - complete power-user surface with every registered tool, resource, and prompt\n- `management` - project lifecycle, adoption, GitHub sync scaffolding, manifest import/export, and starter templates\n- `intake` - project intent, stakeholders, concerns, sources, citations, and requirements\n- `architecture` - architecture viewpoints, views, elements, and coverage\n- `planning` - delivery plans, roles, agents, milestones, work items, mockups, risks, releases, and deployments\n- `verification` - verification plans, cases, runs, anomalies, check evidence, and readiness\n- `governance` - reviews, change control, release readiness, impact analysis, and evidence gaps\n- `readonly` - read-only project state, resources, summaries, traces, and lookup tools\n\nThe matching HTTP endpoints are `/mcp/all`, `/mcp/management`, `/mcp/intake`, `/mcp/architecture`, `/mcp/planning`, `/mcp/verification`, `/mcp/governance`, and `/mcp/readonly`.\n\nThe `readonly` and `all` surfaces also expose MCP apps for the project dashboard, gate status, requirement explorer, and trace graph. These apps render project health, readiness, implementation state, trace context, and resource links without granting write tools.\n\nFor project bootstrap and sync setup, connect to `management` or `all`. For broad local exploration, `all` is the most convenient starting surface; use role-scoped surfaces when a client should advertise a narrower tool set.\n\nMockup generation is handled through the `planning` and `all` surfaces. Agents\ncan read an owner-specific mockup design brief, upsert named mockup\nalternatives, list mockup coverage across a project, filter to owners missing\ncoverage, and delete one owner's mockup set before regeneration. Mockup upserts\nreturn non-blocking quality warnings for brittle patterns such as external\nassets or whole-screen state pickers; materially different screens should\nusually be separate named mockups.\n\n## GitHub Sync\n\nThe `growth-sync` GitHub Action mirrors a repository's delivery activity into Growth: pull requests become delivery links, CI runs become check evidence, and deployments and published releases become deployment and release records on the bound project.\n\nIf the repository uploads a `growth-evidence` artifact from browser tests, the sync can also post a visual evidence gallery and cite it on the resolved work item.\n\n### Install in an adopter repository\n\nThe quickest path is the `scaffold-github-sync` MCP tool. Given a project, it returns a ready-to-commit workflow file and the remaining one-time setup steps.\n\nTo wire it up by hand instead:\n\n1. Copy [`actions/growth-sync/workflow.example.yml`](actions/growth-sync/workflow.example.yml) to `.github/workflows/growth-sync.yml` in the repository you want to track.\n2. Ask the Growth operator to install the repository secret and variable:\n\n   ```bash\n   php artisan growth-sync:install \u003cproject-id\u003e \u003csync-user-email\u003e --growth-url=https://growth.example.com\n   ```\n\n   The command mints a workspace-bound Passport token with the `mcp:use` scope and writes it directly to `GROWTH_MCP_TOKEN` in GitHub Secrets without printing it. It also writes `GROWTH_URL` as a repository variable.\n3. In Growth, set the project's `github_repo` field to the repository in `owner/repo` form so deployment and release events resolve to it.\n4. If your CI runs on GitHub Actions, edit the `workflow_run.workflows` list in the copied workflow to name your CI workflow or workflows.\n\n### CI sync\n\nCI runs are recorded as check evidence through two triggers:\n\n- `workflow_run` - for GitHub Actions CI. GitHub does not deliver `check_run` events for checks its own Actions create, so Actions CI is captured here instead. The `workflow_run.workflows` list names the CI workflows to watch; it cannot wildcard.\n- `check_run` - for third-party CI, such as CircleCI or Buildkite, whose checks are created by their own GitHub Apps.\n\nBoth resolve the PR from the event payload. Runs triggered by fork pull requests carry no PR reference and are skipped.\n\n### Attribution\n\nPull request and CI sync attribute each event to either a work item or, for CR-only work, a change request. The first source that resolves wins:\n\n1. `Growth-Work-Item: \u003cwork-item-id\u003e` commit trailer.\n2. `Growth-Change-Request: \u003cchange-request-id-or-CR-number\u003e` commit trailer.\n3. `WI-\u003cnumber\u003e` branch reference, such as `WI-42-add-login` or `feature/wi-42`.\n4. `CR-\u003cnumber\u003e` branch reference, such as `CR-7-doc-fix` or `feature/cr-007`.\n5. Work item branch delivery link, bound with `upsert-delivery-link` using type `branch`.\n6. Change request branch delivery link, bound with `upsert-change-request-delivery-link` using type `branch`.\n\nThe last matching trailer wins if several of the same trailer are present. A resolved trailer also binds the same-repository branch, so later trailer-less events on it still attribute. Fork pull requests do not create or use branch bindings because the same head branch name can exist in several forks.\n\nCheck-run evidence remains work-item scoped. If a CI event resolves only to a change request, growth-sync records no check-run evidence and does not create an unattributed-event exception. An event that matches no source is recorded as unattributed and surfaces on the Evidence page; the sync itself is not errored.\n\n### Action inputs\n\n| Input          | Required | Description                                         |\n| -------------- | -------- | --------------------------------------------------- |\n| `growth-url`   | yes      | Base URL of the Growth instance.                    |\n| `growth-token` | yes      | Passport token with the `mcp:use` scope.            |\n| `github-token` | no       | Defaults to `${{ github.token }}` for commit reads. |\n\nThe workflow triggers on `pull_request` (`opened`, `synchronize`, `closed`), `check_run` (`completed`), `workflow_run` (`completed`), `deployment_status`, and `release` (`published`).\n\n## Architecture Notes\n\nThe repo keeps product and architecture notes in:\n\n- [`CONTEXT.md`](CONTEXT.md) - domain vocabulary and relationships\n- [`ROADMAP.md`](ROADMAP.md) - current product capability map\n- [`docs/architecture`](docs/architecture) - design notes and ADR-adjacent discovery\n- [`docs/adr`](docs/adr) - accepted architectural decisions\n\nUse the project vocabulary in `CONTEXT.md` when adding tools, resources, docs, or UI copy. In particular, Growth distinguishes client agents, MCP sessions, capability surfaces, roles, personas, lenses, and agent principals.\n\n## License\n\nGrowth is open-sourced under the GNU Affero General Public License v3.0 or later. See [`LICENSE`](LICENSE).\n\nForks, experiments, issues, and contributions are welcome.\n\nCommercial hosting, support, implementation, and consulting are available from Datashaman.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatashaman%2Fgrowth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdatashaman%2Fgrowth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdatashaman%2Fgrowth/lists"}