Skip to content
pentaglyph

Digital twin downstream — Layer ② Process binding

What this is. A worked example of how a downstream project — a digital twin platform that embeds pentaglyph-docs as a git subtree under libs/pentaglyph-docs/ — plans to bind Layer ② Process to its concrete operating environment after the upstream pentaglyph self-architecture (Phases 0-5) was merged. The patterns generalise; specific project names, ticket IDs, and contributor names are redacted.

MetadataValue
Case study typeLayer ② Process binding (concrete-from-abstract)
Downstream archetypeDigital twin platform (private, regulated industry)
Upstream canon versionpentaglyph self-architecture Phases 0-5
StatusIn progress — three follow-up User Stories planned

1. TL;DR

Section titled “1. TL;DR”

After the upstream pentaglyph self-architecture work was merged (5 layers ⓪–⑤ surfaced + ADRs 0001-0009 + Layer ② canon bindings), the downstream team noticed a gap that pentaglyph itself does not — and should not — fill:

“pentaglyph binds canons (Scrum Guide 2020 / North 2003 BDD / Beck 2002 TDD) by linking out. But our team has not yet picked the concrete Sprint cadence, CI/CD ↔ Sprint trigger, or BDD/TDD tool — those are deliberately out of pentaglyph’s scope. Without those concrete bindings, a new joiner cannot ‘just adopt the kit’ — they will improvise, drift, and lose the upstream benefits.”

This case study documents:

  1. What pentaglyph Layer ② provides (the upstream side, complete).
  2. What pentaglyph deliberately leaves out-of-scope (and why — the four-axis test in STRATEGY §9.1).
  3. Three concrete bindings the downstream chose:
    • Track 1: Scrum cadence binding → docs/detailed-design/cross-cutting/development-lifecycle/scrum-cadence.md
    • Track 2: CI/CD ↔ Sprint integration → extend docs/detailed-design/infra/ci-cd/CICD.md
    • Track 3: BDD/TDD tool adoption ADR → docs/arc42/09-decisions/00XX-bdd-tdd-tool-adoption.md

2. What pentaglyph Layer ② provides (upstream)

Section titled “2. What pentaglyph Layer ② provides (upstream)”

Phase 2 of the self-architecture roadmap delivered these bindings in template/docs/design-guide/:

FileCanon boundStatus
dev-cycle.mdScrum Guide 2020 (Schwaber & Sutherland)Stable
bdd-workflow.mdDan North 2003 / Adzic 2011 SbEStable
tdd-workflow.mdBeck 2002 / FowlerStable
dod-dor.mdDefinition templates (Cohn / industry baseline)Stable
_binding-a-new-process.mdMeta-doc: how to bind a new process canonStable

Crucially, every binding doc states the same boundary in different words:

“No tool selection. Whether you track Sprint Backlog in Jira / Linear / Azure DevOps Boards / GitHub Projects / paper is a Layer ③ Automation concern.”

“Sprint cadence is project-specific. This binding does not prescribe 1-week / 2-week / 4-week Sprints — pick what matches team / domain.”

This is the deliberate hole. The hole is the point — it lets pentaglyph stay domain-neutral and ten-year-stable. But the hole has to be filled per project.

3. What pentaglyph deliberately leaves out (and why)

Section titled “3. What pentaglyph deliberately leaves out (and why)”

The four-axis test from STRATEGY.md §9.1 decides what pentaglyph binds vs. what it leaves to downstream:

AxisMeansIf all four ✅If any ❌
Day-1 necessityProject needs it on day 1, can’t postponeBind itLeave to downstream
Switching costCostly to change after the factBind itLeave to downstream
External canonA stable, free, authoritative document existsBind to it (link-out)Don’t invent one
Domain neutralityWorks in regulated / startup / B2B / OSS / AI / embeddedBind itLeave to downstream

Applying this to the downstream’s gap:

Concrete decisionDay-1?Switch costExternal canonDomain-neutral?Pentaglyph binds?
Scrum cadence (1-week vs 2-week)✅⚠️ medium❌ (Scrum Guide silent)❌ (team-dependent)NO — leave to downstream
CI tool choice✅🔴 high❌ (no canon)❌ (cloud-dependent)NO — Layer ③ Automation
BDD tool⚠️🟡 low-medium❌ (multiple tools)❌ (language-dependent)NO — leave to downstream
BDD / TDD / Scrum as concepts✅🔴 high✅✅YES — already bound in Phase 2

So the three Tracks below all fall on the “leave to downstream” side of the line. That is the intended architecture, not a pentaglyph gap.

4. The three concrete bindings (Tracks)

Section titled “4. The three concrete bindings (Tracks)”

Each Track corresponds to one User Story under a parent Feature. Each is sized for one focused day of work and is independent — can be done in any order or in parallel.

4.1 Track 1 — Scrum cadence binding

Section titled “4.1 Track 1 — Scrum cadence binding”

Goal: Author docs/detailed-design/cross-cutting/development-lifecycle/scrum-cadence.md as the downstream’s project-specific override of pentaglyph’s design-guide/dev-cycle.md. The authoritative answer to “How does Scrum run on this project?”

Content (must include all):

  1. Cadence: 1-week Sprint (Mon-Fri).
  2. Events with timeboxes:
    • Sprint Planning: Monday, 2h max
    • Daily Scrum: 15 min, asynchronous (geographically dispersed team)
    • Sprint Review: Friday, 1h max — includes DoD gate + Velocity recompute
    • Sprint Retro: Friday after Review, 45 min max
  3. Roles (Scrum Guide 2020 mapping):
    • Product Owner: domain champion / funder
    • Scrum Master: distributed across AI-agent skills (impediment detection, DoD gate, facilitation). Non-standard but intentional.
    • Developers: AI-agent roles + human reviewers
  4. Artefact mapping — abstract pentaglyph list instantiated for this project’s ticket system.
  5. Version bumping — Sprint Review triggers semver minor bump + tag.
  6. Override declaration — overrides: libs/pentaglyph-docs/template/docs/design-guide/dev-cycle.md.

4.2 Track 2 — CI/CD ↔ Sprint integration

Section titled “4.2 Track 2 — CI/CD ↔ Sprint integration”

Goal: Extend docs/detailed-design/infra/ci-cd/CICD.md with the Sprint-cadence interplay that is currently undocumented. Not about adding new CI features — about naming the existing release ceremony so newcomers stop reverse-engineering it.

Content:

  1. Trigger matrix — for each pipeline, what fires it and which Sprint event it maps to.
  2. Sprint-Review release flow — the canonical sequence from DoD gate → version bump → tag → CD-prod auto-fire → post-deploy smoke test.
  3. Cold-start / drift handling — week-1 of Sprint re-bake fragility patterns.
  4. Path-aware CI skip rules — what triggers full CI vs fast path.
  5. Failure runbook — link to recent CI postmortems.

4.3 Track 3 — BDD / TDD tool adoption ADR

Section titled “4.3 Track 3 — BDD / TDD tool adoption ADR”

Goal: Decide which BDD and TDD tools the downstream adopts and record the decision as a MADR ADR.

Decision drivers (pre-filled in the ADR):

  1. Existing test stack — extensive unit test coverage, no Gherkin / .feature files yet.
  2. Current AC practice — Connextra format + checkbox; some AC use Given/When/Then but not executable.
  3. Test maturity — high in unit / E2E; marginal value of BDD on top is moderate, not high.
  4. PoC vs production — multi-tenant + regulated rollout increases the value of executable AC for compliance.
  5. AI-agent compatibility — adding pytest-bdd would add a layer the agents need new prompts for.

Candidate decisions:

OptionVerdict
A. Adopt pytest-bdd for new features onlyMaintains alignment with SbE; adds friction to agent workflow; locks in tool early
B. Defer BDD adoption until multi-tenant rolloutAvoids premature tool commitment; keeps option open; risks AC drift
C. Adopt G/W/T as AC notation only (no .feature files), TDD-first via existing unit testsCheapest; matches current habit; loses “executable AC” benefit; aligns with pentaglyph upstream “tool-free first” guidance

Recommendation: Option C for PoC, revisit at multi-tenant milestone.

5. Generalisable patterns

Section titled “5. Generalisable patterns”

Even with project-specific details redacted, these patterns travel:

  1. Three-Track decomposition — splitting one Feature into Cadence + Tooling-integration + Decision-ADR keeps each PR shippable in a day.
  2. Override declaration in front-matter — overrides: libs/pentaglyph-docs/template/docs/design-guide/<file> makes pentaglyph alignment checkable by static linting later.
  3. Distributed Scrum Master role across AI agents — non-standard but viable for small, AI-augmented teams; document explicitly to avoid Scrum Guide compliance surprises.
  4. “Tool-free first” for BDD adoption — favouring G/W/T as a writing convention before committing to a runner is consistent with pentaglyph’s domain-neutrality philosophy.

6. Lessons learned

Section titled “6. Lessons learned”

To be appended after the three Tracks merge. Especially:

  • Did the four-axis test correctly predict the binding boundary?
  • Any pieces that should be pushed back into pentaglyph upstream?
  • Any downstream-specific binding actually generic enough to be a kit default?

7. References

Section titled “7. References”