drivestream-lab/launchpad

1. What this repo is

- Launchpad is a Python-based factory kit for engineering orgs.

- It combines configuration-driven org bootstrapping, SDD/harness conventions, and tenant-specific work seeding.

- Architecturally, it is not an application backend; it is a CLI tool plus playbook/docs plus templates that act on a separate private tenant repo.

2. Primary runtime boundary

- The launchpad/ package is the executable core, exposed through bin/launchpad and launchpad.__main__.

- The repo itself is mostly control plane logic: it reads YAML/config, generates files, and talks to forge APIs when needed.

- The “real customer data” and operating truth live outside this repo in a private <client>-meta tenant repository.

3. Two main operational lanes

- Factory lane: org setup, gitflow policy, project/board bootstrapping, and work seeding into GitHub or GitLab.

- Harness lane: repo-local scaffolding, harness pinning, rules/skills sync, and verification for app repositories.

- These are separated by intent: factory commands mutate forge/tenant state, while harness commands manage the standardized repo agent surface.

4. Tenant repository as the main data source

- The private tenant repo contains client-specific YAML and content under config/, work/, prd/, planning/, programs/, and wiki/.

- Launchpad reads this tenant content to decide what to provision or publish.

- This is a key boundary for architecture diagrams: Launchpad code is generic, while tenant repos carry org-specific truth and manifests.

5. Configuration-driven provisioning

- The config subsystem centers on YAML schemas with apiVersion: launchpad/v1.

- launchpad/config.py, paths.py, clients.py, and related modules appear to manage locating tenant roots, client registries, and file paths.

- The architecture depends on filesystem-based config discovery more than long-lived server state.

6. Forge integration layer

- launchpad/github_client.py, github_ops.py, and forge.py represent the GitHub side of the factory.

- launchpad/adapters/gitlab/ provides a separate adapter path for GitLab, currently described as partial support.

- The design suggests a forge abstraction where GitHub is the primary implementation and GitLab is an adapter with narrower scope.

7. Org bootstrap and policy enforcement

- bootstrap_org.py, bootstrap_teams.py, gitflow.py, and gitflow_policy.py implement org-level setup and enforcement.

- These modules likely translate tenant config into forge-side resources such as org structure, teams, branch rules, and project policies.

- In the mental model, this is the “infrastructure as code” part of the repo, except the target is an engineering org forge.

8. Work seeding and issue creation flow

- seed_work.py is the bridge from tenant work manifests to forge issues/boards.

- Example manifests live in examples/tenant-meta/work/ and examples/onboarding-*.yaml.

- Data flow: tenant work YAML → Launchpad parser/model → forge adapter → issues/labels/board entries.

9. Harness subsystem

- launchpad/harness.py, verify/, factory_verify.py, doctor.py, issue_types.py, and wiki.py support repo conformance and publication tasks.

- Harness commands manage pinned rules, agent skills, and repo-local metadata such as AGENTS.md and .harness-pin.yaml.

- verify/runner.py and verify/checks.py indicate a rule/check framework that validates repo state against tenant configuration.

10. Scaffolding subsystem

- launchpad/scaffold/ is a template-driven repo/service generator.

- profiles.py and run.py indicate profile-based scaffolds, with a CLI wrapper in scaffold/cli.py.

- The fixture under tests/fixtures/scaffold-python-minimal/ shows scaffolding is meant to produce a new service skeleton, not just modify existing repos.

11. Onboarding subsystem

- launchpad/onboarding/ is a separate workflow engine for planning and applying onboarding from an onboarding.yaml-style spec.

- The presence of interview.py, plan.py, render.py, templates_gen.py, and registry.py suggests it collects requirements, builds an onboarding plan, and renders outputs.

- This subsystem is distinct from factory bootstrap: it is about client onboarding workflow, not org resource provisioning alone.

12. Documentation and playbook as architecture inputs

- playbook/ and docs/ are not decorative; they encode operating model, SDD rules, and repo layout expectations.

- Templates under templates/ define canonical repo content such as AGENTS.md, CODEOWNERS, issue templates, CI workflows, and harness pins.

- For diagrams, these should be treated as authoritative templates/standards consumed by scaffold/sync commands, not as runtime code.

13. Examples and tests define the contract

- examples/tenant-meta/ is a full sample tenant skeleton showing the expected client-side file structure.

- tests/test_onboarding.py and tests/test_scaffold.py indicate the two most important executable contracts are onboarding and scaffolding behavior.

- The CI workflow in .github/workflows/ci.yml validates the package and these flows in automation.

14. External services and operational dependencies

- GitHub is the primary forge; GitLab is supported in a narrower adapter path.

- Private rules repositories and the external prayog-skills bundle are part of the harness boundary, but intentionally not shipped as plain content inside the public kit.

- GITHUB_TOKEN-backed operations and multi-machine client registries indicate the tool is designed for operator-run automation, not a self-hosted daemon.

15. The simplest architecture picture

- Launchpad repo provides CLI, templates, and policy logic.

- Tenant repo provides client truth and manifests.

- Forge receives generated org/project/issue state.

- Private rules/skills define the agent constitution and repo behavior.

- The key flow is: tenant config and work specs in → Launchpad transforms and validates → forge and repo artifacts out.