docs: add Corp pilot onboarding guide

2026-08-27 21:53:44 +00:00
parent 1226329a7a
commit 9e6514de51
5 changed files with 175 additions and 4 deletions
@@ -0,0 +1,23 @@
+---
+title: "Ways of Working"
+description: "Use the shared operating practices for participating safely and effectively in the Corp v1 pilot."
+slug: /
+sidebar_position: 1
+---
+
+# Ways of Working
+
+Corp v1 is a governed AI-assisted delivery pilot. People set outcomes, authority, and constraints; Hermes helps turn those decisions into traceable designs, code, documentation, releases, and operated evidence.
+
+Use this area to understand how to join the pilot, where work belongs, how decisions become delivery, and which evidence is required before something is called complete.
+
+## Start here
+
+1. Read [Onboarding](./onboarding) before contributing.
+2. Find your project in the [project registry](/projects/).
+3. Confirm your responsibilities in the [team](/teams/) and [member](/members/) registries.
+4. Follow the [project lifecycle](/governance/project-lifecycle/) and the authority recorded for your project.
+
+## Core principle
+
+Keep conversation, decisions, implementation, deployment, and runtime proof connected—but do not treat them as the same thing. An approved idea is not implemented work; a merged change is not a deployed change; a healthy runtime is not release or product acceptance.
@@ -0,0 +1,117 @@
+---
+title: "Onboarding"
+description: "Join the Corp v1 pilot with the right access, context, channel routing, authority, security practices, and evidence expectations."
+sidebar_position: 1
+---
+
+# Onboarding
+
+Use this page when joining the Corp v1 pilot or entering a project for the first time. You should finish with the right access, a clear role, and enough context to contribute without bypassing project governance.
+
+## What the pilot is
+
+Corp v1 tests whether one AI agent can support several focused project workstreams while people retain explicit authority and durable oversight. The pilot currently includes:
+
+- [AeroSim](/projects/aerosim/)
+- [Maze Next Gen](/projects/mazeng/)
+- [E-Shop v1](/projects/eshopv1/)
+
+The [Board](/board/) governs project kickoff, closure, and changes to the main Corp v1 operating model. Each project has its own sponsor, team, approved scope, repositories, documentation, Discord category, and preserved authority decisions.
+
+## Your first 20 minutes
+
+1. **Confirm your identity and role.** Check the [member registry](/members/) and your [team record](/teams/). If either is wrong, raise it before taking ownership of work.
+2. **Open the project record.** Read its purpose, initial deliverable, current status, resources, and outstanding gates in the [project registry](/projects/).
+3. **Open the project documentation.** It is the durable source for scope, architecture, design, Kanban state, ways of working, engineering guidance, and release evidence.
+4. **Verify Discord access.** Every project has one dedicated `corp-v1-<code>` category with seven lifecycle channels. Confirm that you can see the channels needed for your role and read their pinned guidance.
+5. **Verify Gitea access.** Confirm access to the project and skills organizations through the appropriate teams. Do not request direct repository access when team membership is the intended route.
+6. **Choose one current outcome.** Start from an existing Epic, Feature, task, issue, design package, or release gate. Do not create parallel records because an item is difficult to find.
+
+## Use the seven channels correctly
+
+Work moves through this shared lifecycle:
+
+```text
+General → Scope → Architecture → UI/UX → Kanban → Delivery → Releases
+```
+
+| Channel | Use it for |
+|---|---|
+| **General** | Project-wide direction, coordination, questions, outcomes, and cross-channel issues |
+| **Scope** | Ideas, Epics, Features, value, acceptance outcomes, and product decisions |
+| **Architecture** | Solution design, interfaces, constraints, risks, and implementation task definitions |
+| **UI/UX** | User journeys, Penpot designs, responsive behavior, accessibility, and implementation handoff |
+| **Kanban** | Flow visibility, task admission, sequencing, dependencies, and blockers |
+| **Delivery** | Implementation, tests, reviews, CI, build health, and delivery evidence |
+| **Releases** | Version readiness, changelogs, deployment approval, rollout, rollback, and runtime verification |
+
+Post in the channel that owns the decision or artifact. Cross-link evidence instead of copying whole conversations between channels. Keep one project’s information inside that project’s seven-channel boundary unless a Board-level concern requires escalation.
+
+## Understand authority
+
+- **Board authority** covers project kickoff, project closure, and changes to `corp-v1--main`.
+- **Project-team authority** covers decisions inside the project’s approved boundary.
+- **Hermes authority** is project-specific. It may range from preparing proposals to full delegated delivery and merge authority. Use the preserved project record and channel skill; never infer authority from activity, silence, CI success, or an agent statement.
+- **Explicit gates remain explicit.** A decision must identify the item, actor, conditions, and evidence. Delegation changes who may decide; it does not remove security, quality, traceability, or validation gates.
+
+When authority is unclear, stop at a reversible proposal and ask in the owning channel.
+
+## Know what “done” means
+
+Keep these states separate:
+
+1. **Approved** — an authorized person or delegate accepted the exact scope or decision.
+2. **Implemented** — source changes exist and passed the required local/review checks.
+3. **Merged** — the reviewed change is integrated into the repository’s default branch.
+4. **Deployed / runtime verified** — the intended immutable revision is running and has passed live readback or acceptance checks.
+5. **Released / accepted** — the project’s release authority approved the version and required outcomes.
+
+Always state the highest level actually proven and link the evidence. Do not use “live” as a shortcut for release approval or product maturity.
+
+## Security and credentials
+
+- Never paste passwords, tokens, API keys, connection strings, secret values, or Bitwarden object metadata into Discord, issues, repositories, prompts, screenshots, or documentation.
+- Use the approved SSO and secret-injection paths. A credential being available does not authorize unrelated access, account administration, spending, or destructive work.
+- Record secret **names and readiness only** when governance requires it.
+- Report suspected exposure immediately in the owning project and follow the approved rotation path.
+- Treat private project repositories, project-channel history, and customer or operational data as project-bound information.
+
+## How to make a useful contribution
+
+A useful contribution is small enough to review and complete, but durable enough to help the next person:
+
+- start from a stable item or create a clearly marked proposal;
+- cite the source message, decision, requirement, design, issue, or runtime observation;
+- work in the owning channel and canonical repository;
+- preserve project naming, branch, testing, and documentation conventions;
+- run the required validation and match CI to the exact commit;
+- read back remote and deployed state before claiming completion;
+- report the outcome, evidence, remaining gates, owner, and next action concisely.
+
+If a task crosses channels, finish the source-owned result and hand off one clear requested action with evidence and unresolved risks.
+
+## Where truth lives
+
+| Information | Authoritative location |
+|---|---|
+| Portfolio governance, Board decisions, teams, and project registry | This Corp v1 portal |
+| Product scope and project delivery records | Project documentation repository and deployed documentation |
+| Source, reviews, commits, CI, and releases | Project Gitea repositories |
+| Discussion, approvals, coordination, and handoffs | Exact project Discord channels and message IDs |
+| Deployment and runtime state | GitOps source, Argo CD, workload state, and live acceptance evidence |
+| Editable interface design | Project-owned Penpot files linked from project records |
+
+No single status message replaces these sources. Reconcile them when they disagree.
+
+## Onboarding complete
+
+You are ready to contribute when you can answer:
+
+- Which project and outcome am I supporting?
+- What is my role and decision authority?
+- Which channel owns my next action?
+- Where is the canonical record?
+- What evidence is required before I call it complete?
+- Which security or release gates still apply?
+
+If any answer is missing, ask in the project’s **General** channel and link the record you already checked.