@tryinget/pi-designmd-foundry 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,78 @@
1
+ MIT License (with OpenAI/Anthropic/xAI/PRC Frontier Labs Rider)
2
+
3
+ Copyright (c) contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ ADDITIONAL RIDER / RESTRICTION (OpenAI / Anthropic / xAI / PRC Frontier Labs):
13
+
14
+ This rider is part of the "conditions" of this License. In the event of any
15
+ conflict between this rider and any other portion of this License, this rider
16
+ controls.
17
+
18
+ "Restricted Parties" means OpenAI, L.L.C.; Anthropic, PBC; xAI Corp.; and the
19
+ following PRC frontier AI labs and related entities: Baidu (including ERNIE-
20
+ related entities), Alibaba and Alibaba Cloud (including Qwen-related entities),
21
+ Tencent (including Hunyuan-related entities), ByteDance (including Doubao/Seed-
22
+ related entities), DeepSeek, Zhipu AI, Moonshot AI, MiniMax, 01.AI
23
+ (Lingyiwanwu), and iFlyTek. "Restricted Parties" also includes any of their
24
+ respective Affiliates and any person or entity acting directly or indirectly
25
+ on behalf of, for the benefit of, or under the direction of any of the
26
+ foregoing (including any officer, director, employee, contractor, agent,
27
+ consultant, service provider, or representative).
28
+
29
+ Notwithstanding any other provision of this License, no rights are granted to
30
+ any Restricted Party. Any purported license, sublicense, assignment, transfer,
31
+ or other permission to any Restricted Party is null and void absent the
32
+ express prior written permission of the copyright holders.
33
+
34
+ You may not provide, disclose, distribute, sublicense, sell, lease, lend,
35
+ host, make available, or otherwise permit access to the Software or any
36
+ derivative work of the Software (as defined in applicable copyright law)
37
+ (collectively, "Derivative Works") to or for any Restricted Party.
38
+
39
+ For purposes of this rider, "use" includes, without limitation: copying,
40
+ modifying, merging, publishing, distributing, sublicensing, selling,
41
+ transferring, making available, hosting, deploying, executing, benchmarking,
42
+ testing, analyzing, indexing, or incorporating the Software or any Derivative
43
+ Works into any dataset, training corpus, evaluation harness, or pipeline for
44
+ machine learning or other automated systems.
45
+
46
+ This rider applies to the Software and all Derivative Works. As a condition of
47
+ use, you agree that this rider is a precondition to exercising any rights
48
+ under this License, and you agree that any distribution of the Software or any
49
+ Derivative Works must include this rider provision unmodified.
50
+
51
+ Any breach of this rider automatically and immediately terminates the
52
+ permissions granted by this License. Upon termination, you must immediately
53
+ cease all use and distribution of the Software and any Derivative Works and
54
+ destroy all copies under your control.
55
+
56
+ You agree that a breach of this rider would cause irreparable harm and that
57
+ the copyright holders may seek injunctive or other equitable relief to enforce
58
+ this rider, in addition to any other remedies available at law. To the maximum
59
+ extent permitted by applicable law, the prevailing party in any action to
60
+ enforce this rider shall be entitled to recover reasonable attorneys' fees and
61
+ costs.
62
+
63
+ For purposes of this rider, "Affiliate" means any entity that directly or
64
+ indirectly controls, is controlled by, or is under common control with the
65
+ specified party. "Control" means ownership of more than 50% of the voting
66
+ securities or other ownership interest, or the power to direct management or
67
+ policies by contract or otherwise.
68
+
69
+ The above copyright notice and this permission notice shall be included in all
70
+ copies or substantial portions of the Software.
71
+
72
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
73
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
74
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
75
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
76
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
77
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
78
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,193 @@
1
+ ---
2
+ summary: "Overview and quickstart for monorepo package @tryinget/pi-designmd-foundry."
3
+ read_when:
4
+ - "Starting work in this package workspace."
5
+ system4d:
6
+ container: "Monorepo package scaffold for pi extension delivery."
7
+ compass: "Ship safe package-level iterations inside a shared workspace."
8
+ engine: "Plan -> implement -> validate -> coordinate with monorepo release flow."
9
+ fog: "Drift risk if package scripts diverge from monorepo root conventions."
10
+ ---
11
+
12
+ # @tryinget/pi-designmd-foundry
13
+
14
+ Pi extension and skill package for using DesignMD Foundry as a local-first design contract tool surface.
15
+
16
+ This package does **not** reimplement DesignMD Foundry. It wraps the DesignMD Foundry CLI so Pi agents can reliably lint `DESIGN.md`, export design artifacts, generate handoff prompts, import DTCG/Penpot token JSON, parse palette text, and inspect integration readiness.
17
+
18
+ No harnessed LLM provider is bundled here. Pi remains the agent harness; Foundry remains the design contract authority.
19
+
20
+ When `DESIGNMD_SESSION_ENDPOINT` is set, tools also report start/pass/fail activity and generated artifacts into a running DesignMD Foundry Watch Mode session. Reporting is optional and fail-open: tools still work when no Foundry UI/server is running.
21
+
22
+ - Workspace path: `packages/pi-designmd-foundry`
23
+ - Release component key: `pi-designmd-foundry`
24
+ - Release config mode: `component`
25
+
26
+ ## Tools
27
+
28
+ - `designmd_lint` — lint a `DESIGN.md` file.
29
+ - `designmd_export` — export `css`, `oat`, `tailwind`, `dtcg`, `tokens`, `agent-prompt`, `xstate`, `rive`, or `json`.
30
+ - `designmd_agent_prompt` — convenience wrapper for `agent-prompt` export.
31
+ - `designmd_oat_visual_snapshot` — generate token-preserving Oat visual snapshot HTML for manual review.
32
+ - `designmd_openpencil_prompt` — build an OpenPencil handoff prompt.
33
+ - `designmd_openpencil_info` — inspect a `.fig` / `.pen` file through the verified OpenPencil info adapter.
34
+ - `designmd_openpencil_lint` — lint a `.fig` / `.pen` file through the verified OpenPencil lint adapter.
35
+ - `designmd_openpencil_export` — export a `.fig` / `.pen` file to `svg`, `png`, `jpg`, `webp`, or `fig`; `jsx` is intentionally excluded.
36
+ - `designmd_import_penpot` — convert DTCG/Penpot token JSON into DESIGN.md text.
37
+ - `designmd_palette_from_text` — parse or apply Pigmnts-style hex palette text.
38
+ - `designmd_penpot_mcp_inspect` — read-only inspect of the active Penpot file through the official Penpot MCP server.
39
+ - `designmd_penpot_mcp_bridge` — plan or explicitly apply one bounded `designmd.canvas-bridge.v1` board create/update mutation through the official Penpot MCP server; update selectors only rebuild selected/latest DesignMD bridge boards.
40
+ - `designmd_penpot_mcp_export` — read-only SVG export of an existing DesignMD bridge board through the official Penpot MCP server.
41
+ - `designmd_session_plan` — build or materialize a local `designmd.session-plan.v1` Watch Mode planning packet without claiming canonical AK/society authority.
42
+ - `designmd_session_variants` — build or materialize local `designmd.session-variants.v1` proposal lanes without claiming accepted durable variants or canonical direction.
43
+ - `designmd_session_handoff` — build or materialize a local `designmd.session-handoff.v1` prompt for one executable variant lane without claiming canonical authority.
44
+ - `designmd_session_guided_run` — build or materialize the full local `designmd.guided-design-run.v1` loop (plan, memory, variants, handoff, report-back instructions) without executing Pi or claiming canonical authority.
45
+ - `designmd_session_browser_agent_handoff` — build or materialize a local `designmd.browser-agent-handoff.v1` prompt for optional browser-side review such as Sitegeist without granting mutation or promotion authority.
46
+ - `designmd_session_closeout` — build or materialize a local `designmd.session-closeout.v1` Watch Mode evidence packet without claiming canonical AK/society promotion.
47
+ - `designmd_session_promotion_candidate` — build or materialize a local `designmd.promotion-candidate.v1` owner-review packet without promoting, publishing, merging, or mutating AK/society authority.
48
+ - `designmd_visual_dossier_pi_critique` — emit a `designmd.pi-visual-dossier-critique-handoff.v1` packet or markdown handoff prompt over validated visual-source dossier state; critique/handoff only, with no dossier acceptance, `DESIGN.md` mutation, DSPx fitness claim, or AK/society authority.
49
+ - `designmd_readiness` — run DesignMD Foundry's integration readiness probe.
50
+
51
+ Prompt/export modes are deliberately constrained to the Foundry CLI contract: `iterate`, `remix`, `expand`, or `audit`.
52
+
53
+ ## Skill
54
+
55
+ Use the skill when doing UI/design work:
56
+
57
+ ```text
58
+ /skill:designmd-foundry
59
+ ```
60
+
61
+ The skill instructs agents to lint and export design context before implementation, preserve tokens unless a DESIGN.md change is intentional, and keep external integrations honest about readiness.
62
+
63
+ ## Runtime dependencies
64
+
65
+ This package expects pi host runtime APIs and declares them as `peerDependencies`:
66
+
67
+ - `@earendil-works/pi-coding-agent`
68
+ - `@earendil-works/pi-ai`
69
+
70
+ When using UI APIs (`ctx.ui`), guard interactive-only behavior with `ctx.hasUI` so `pi -p` non-interactive runs stay stable.
71
+
72
+ ## Package checks
73
+
74
+ Run from package directory:
75
+
76
+ ```bash
77
+ npm install
78
+ npm run check
79
+ ```
80
+
81
+ Run from monorepo root through the canonical package gate:
82
+
83
+ ```bash
84
+ bash ./scripts/package-quality-gate.sh ci packages/pi-designmd-foundry
85
+ ```
86
+
87
+ The generated package-local `scripts/quality-gate.sh` is a thin wrapper that searches upward for the canonical monorepo root gate.
88
+ If you validate the package outside the monorepo tree, set `PACKAGE_QUALITY_GATE_SCRIPT` to the canonical `pi-extensions` root gate path.
89
+
90
+ ## AK task/work-item operations
91
+
92
+ This package is a monorepo member, not a git root.
93
+ Use the monorepo-root AK wrapper for task/work-item operations:
94
+
95
+ ```bash
96
+ # from the monorepo root
97
+ ./scripts/ak.sh --doctor
98
+ ./scripts/ak.sh task ready
99
+
100
+ # from this package directory
101
+ ../../scripts/ak.sh --doctor
102
+ ../../scripts/ak.sh task show <id> -F json
103
+ ```
104
+
105
+ ## Documentation placement
106
+
107
+ Use:
108
+ - `docs/project/` for dated RFCs, runbooks, and evidence/progress notes
109
+ - `docs/adr/` for adopted architecture decisions
110
+
111
+ Avoid creating new package-local `docs/dev/` trees.
112
+
113
+ ## Watch Mode reporting
114
+
115
+ To watch Pi tool progress in the DesignMD Foundry UI, start Foundry and point this package at its session API:
116
+
117
+ ```bash
118
+ export DESIGNMD_SESSION_ENDPOINT=http://127.0.0.1:8788/api/session
119
+ # optional existing session override:
120
+ export DESIGNMD_SESSION_ID=ses_...
121
+ # optional actor label and API token:
122
+ export DESIGNMD_SESSION_ACTOR=pi-designmd
123
+ export DESIGNMD_SESSION_TOKEN=$DESIGNMD_API_TOKEN
124
+ ```
125
+
126
+ Without `DESIGNMD_SESSION_ID`, the adapter reuses the current running session or starts a new one. Output-producing tools attach artifacts such as Oat snapshot HTML, agent prompts, CSS/JSON exports, SVG/path metadata for OpenPencil exports, Penpot MCP bridge plans, bridge-apply proof SVGs, read-only existing-board export SVGs, local session plan packets, local session variant lane packets, local session handoff prompts, local session closeout packets, local promotion candidate packets, and visual-dossier Pi critique/handoff packets.
127
+
128
+ ## DesignMD Foundry root
129
+
130
+ By default the extension looks for DesignMD Foundry at:
131
+
132
+ ```text
133
+ ~/ai-society/softwareco/owned/designmd-foundry
134
+ ```
135
+
136
+ Override with either a tool parameter or environment variable:
137
+
138
+ ```bash
139
+ export DESIGNMD_FOUNDRY_HOME=/path/to/designmd-foundry
140
+ ```
141
+
142
+ ## Live package activation
143
+
144
+ Install the package into Pi from the package directory containing this package's `package.json`:
145
+
146
+ ```bash
147
+ pi install /home/tryinget/ai-society/softwareco/owned/pi-extensions/packages/pi-designmd-foundry
148
+ ```
149
+
150
+ Then in Pi:
151
+
152
+ 1. run `/reload`
153
+ 2. verify with a real command or tool call from this package
154
+
155
+ ## Release metadata
156
+
157
+ This scaffold writes component metadata in `package.json` under `x-pi-template`:
158
+
159
+ - `workspacePath`
160
+ - `releaseComponent`
161
+ - `releaseConfigMode`
162
+
163
+ Use these values when wiring monorepo-level release-please component maps.
164
+
165
+ ## Docs discovery
166
+
167
+ ```bash
168
+ npm run docs:list
169
+ npm run docs:list:workspace
170
+ npm run docs:list:json
171
+ ```
172
+
173
+ ## Stack lane companions
174
+
175
+ This package follows the shared `pi-ts` lane.
176
+ Add companions only when they materially improve clarity or reuse:
177
+
178
+ - `fast-check` for parser/rendering/selection invariants
179
+ - `@cucumber/cucumber` for executable Gherkin/operator workflows
180
+ - `nunjucks` for reusable text/config/prompt/file templates
181
+ - `engineering-pi-ts.ts-quality.md` when the package explicitly adopts deterministic screening with `ts-quality`
182
+
183
+ If this package adopts `ts-quality`, prefer repo-local rollout truth in `docs/project/ts-quality-current-vs-target.md` and keep the detailed adoption doctrine upstream in `~/ai-society/softwareco/owned/ts-quality/docs/adoption/`.
184
+
185
+ ## Copier lifecycle policy
186
+
187
+ - Keep `.copier-answers.yml` committed.
188
+ - Do not edit `.copier-answers.yml` manually.
189
+ - Run update/recopy from a clean destination repo (commit or stash pending changes first).
190
+ - Use `copier update --trust` when `.copier-answers.yml` includes `_commit` and update is supported.
191
+ - In non-interactive shells/CI, append `--defaults` to update/recopy.
192
+ - Use `copier recopy --trust` when update is unavailable (for example local non-VCS source) or cannot reconcile cleanly.
193
+ - After recopy, re-apply local deltas intentionally and run `npm run check`.
File without changes
@@ -0,0 +1,68 @@
1
+ ---
2
+ summary: "Local override notes for the shared engineering-core lane used by this repo."
3
+ read_when:
4
+ - "Aligning implementation decisions with the TypeScript stack baseline."
5
+ - "Reconciling differences between generic TS guidance and pi extension constraints."
6
+ system4d:
7
+ container: "Repo-local deltas on top of shared lane guidance."
8
+ compass: "Keep extension work aligned with reproducible Node/npm release flow."
9
+ engine: "Use shared lane -> apply local override -> validate with repo scripts."
10
+ fog: "External lane guidance may evolve independently of this repo."
11
+ ---
12
+
13
+ # engineering.local (pi extension flavor)
14
+
15
+ Primary lane:
16
+
17
+ - `engineering-core show pi-ts --prefer-repo`
18
+
19
+ Catalog/list commands:
20
+
21
+ ```bash
22
+ uv tool -n run --from ~/ai-society/core/engineering-core engineering-core catalog --pretty
23
+ uv tool -n run --from ~/ai-society/core/engineering-core engineering-core list-disciplines
24
+ uv tool -n run --from ~/ai-society/core/engineering-core engineering-core list-templates
25
+ ```
26
+
27
+ Selected disciplines:
28
+
29
+ - `validation`
30
+ - `testing`
31
+ - `security-privacy`
32
+ - `documentation`
33
+ - `dependency-governance`
34
+ - `design-system`
35
+ - `accessibility`
36
+ - `specification-and-dsls`
37
+ - `engineering-reasoning`
38
+
39
+ Repo-local emphasis:
40
+
41
+ - Runtime/package manager baseline: Node.js 22 + npm (not Bun-first defaults).
42
+ - Release baseline: release-please + `npm run release:check` + npm trusted publishing.
43
+ - Keep package artifacts deterministic via `package.json` `files` allowlist.
44
+ - Lint/format baseline: Biome config in `biome.jsonc` + pinned local `@biomejs/biome` dev dependency.
45
+ - Biome path strategy: lint repo files by default, but exclude artifact/vendor buckets (`external/`, `ontology/`, build outputs, generated/minified files).
46
+ - Quality lane gate: `npm run quality:pre-commit`, `npm run quality:pre-push`, `npm run quality:ci`.
47
+ - Auto-fix workflow: `npm run fix` (before commit or when applying AI-generated diffs).
48
+ - Pin lane metadata in `policy/engineering-lane.json` (`lane: ts`, pinned `engineering_core.ref`).
49
+ - Validate structural/docs invariants with `npm run check`.
50
+ - Optional pi-ts companions (add only when the package actually benefits):
51
+ - `fast-check` for parser/rendering/selection invariants.
52
+ - `@cucumber/cucumber` only when executable operator/workflow scenarios materially improve shared understanding.
53
+ - `nunjucks` for reusable text/config/prompt/file templates when plain typed render functions are no longer enough.
54
+ - `engineering-pi-ts.ts-quality.md` when the package explicitly adopts deterministic screening with `ts-quality`.
55
+ - If the package adopts `ts-quality`, prefer repo-local rollout truth in `docs/project/ts-quality-current-vs-target.md` and keep the detailed adoption doctrine upstream in `~/ai-society/softwareco/owned/ts-quality/docs/adoption/`.
56
+
57
+ ## Repo loop validation
58
+
59
+ `@tryinget/pi-designmd-foundry` adopts `repo-loop-validation-v1` for package-local loop prompt dogfooding. The policy declaration is in `policy/engineering-lane.json`.
60
+
61
+ - `loop-doctor`: `npm run loop-doctor` (non-failing Node/npm/package/git diagnostics)
62
+ - `loop-verify-fast`: `npm run loop-verify-fast` (maps to `quality:pre-commit`)
63
+ - `loop-impact-plan`: `npm run loop-impact-plan` (coarse package impact note plus changed-file listing)
64
+ - `loop-impact-run`: `npm run loop-impact-run` (maps to `npm run check`)
65
+ - `loop-impact-wide`: `npm run loop-impact-wide` (explicit full package gate, also `npm run check`)
66
+ - `loop-landing-check`: `npm run loop-landing-check` (maps to `npm run check`)
67
+
68
+ These commands produce package-local evidence for orchestration prompts. They do not replace Pi runtime install/reload proof, release approval, or monorepo owner authority.
@@ -0,0 +1,34 @@
1
+ ---
2
+ summary: "Compact organization operating model and terminology."
3
+ read_when:
4
+ - "Aligning organization-level purpose, mission, and strategy."
5
+ system4d:
6
+ container: "Organization-level concepts shared across projects."
7
+ compass: "Keep strategy and culture aligned with organization purpose."
8
+ engine: "Purpose -> mission -> vision -> strategic objectives."
9
+ fog: "Terminology drift can create cross-project confusion."
10
+ ---
11
+
12
+ # Organization operating model
13
+
14
+ ```mermaid
15
+ flowchart TD
16
+ OrganizationPurpose("Organization Purpose") -->|defines| OrganizationMission("Organization Mission")
17
+ OrganizationMission -->|leads to| OrganizationVision("Organization Vision")
18
+ OrganizationVision -->|is operationalized by| StrategicObjectives("Strategic Objectives")
19
+ OrganizationPurpose -->|inspires| CoreValues("Core Values")
20
+ CoreValues -->|shape| EthicsPolicy("Ethics Policy")
21
+ CoreValues -->|shape| OrganizationCulture("Organization Culture")
22
+ CoreValues -->|are expressed in| OrganizationCharter("Organization Charter")
23
+ OrganizationCharter -->|influences| EthicsPolicy
24
+ EthicsPolicy -->|guides behavior in| OrganizationCulture
25
+ OrganizationCulture -->|supports| StrategicObjectives
26
+ ```
27
+
28
+ ## Compact terminology
29
+
30
+ - **Organization Purpose**: why the organization exists.
31
+ - **Organization Mission**: what the organization does now.
32
+ - **Organization Vision**: target future state.
33
+ - **Strategic Objectives**: measurable outcomes that realize the vision.
34
+ - **Core Values / Ethics / Culture / Charter**: behavioral system that supports strategy.
@@ -0,0 +1,51 @@
1
+ ---
2
+ summary: "Contribution workflow for this extension repository."
3
+ read_when:
4
+ - "Before opening PRs or submitting local changes."
5
+ system4d:
6
+ container: "Contributor process and quality gates."
7
+ compass: "Small, validated, documented changes."
8
+ engine: "Branch -> implement -> check -> document -> review."
9
+ fog: "Process details may adjust with team scale."
10
+ ---
11
+
12
+ # Contributing
13
+
14
+ ## Workflow
15
+
16
+ 1. Create a focused branch.
17
+ 2. Run `npm run docs:list` and read matched docs before cross-cutting changes.
18
+ 3. Implement one scoped change.
19
+ 4. Run `npm run fix` (Biome auto-fix).
20
+ 5. Run `npm run check`.
21
+ 6. Update docs/changelog where relevant.
22
+ 7. Open PR with concise rationale and validation output.
23
+
24
+ ## Standards
25
+
26
+ - Keep diffs small and reviewable.
27
+ - Preserve markdown frontmatter in generated docs.
28
+ - Prefer explicit scripts over manual one-off commands.
29
+
30
+ ## Biome suppression policy
31
+
32
+ - Prefer fixing the root cause over adding suppression comments.
33
+ - Every `biome-ignore` must include a short rationale after `:`.
34
+ - If a suppression cannot be removed in the same PR, add a tracking reference (`TODO(#123)` or `Issue: #123`).
35
+ - Keep suppressions rule-scoped and line-scoped (no file-wide blanket ignores).
36
+
37
+ Example:
38
+
39
+ ```ts
40
+ // biome-ignore lint/suspicious/noExplicitAny: upstream SDK type gap; TODO(#123) remove after typed client migration.
41
+ ```
42
+
43
+ ## Copier policy
44
+
45
+ - Keep `.copier-answers.yml` in version control.
46
+ - Do not edit `.copier-answers.yml` manually.
47
+ - Run update/recopy from a clean destination repo (commit or stash pending changes first).
48
+ - Use `copier update --trust` when `.copier-answers.yml` includes `_commit` and update is supported.
49
+ - In non-interactive shells/CI, append `--defaults` to update/recopy.
50
+ - Use `copier recopy --trust` when update is unavailable (for example local non-VCS source) or cannot reconcile cleanly.
51
+ - After recopy, re-apply local deltas intentionally and run `npm run check`.
@@ -0,0 +1,47 @@
1
+ ---
2
+ summary: "Lifecycle SOP for extension delivery and maintenance."
3
+ read_when:
4
+ - "Planning, implementing, verifying, releasing, or maintaining extension work."
5
+ system4d:
6
+ container: "End-to-end extension operating procedure."
7
+ compass: "Consistent quality from idea to maintenance."
8
+ engine: "plan -> implement -> verify -> release -> maintain."
9
+ fog: "Unknowns resolved through incremental validation loops."
10
+ ---
11
+
12
+ # Extension SOP
13
+
14
+ ## 1) Plan
15
+
16
+ - Define scope and acceptance criteria.
17
+ - Run `npm run docs:list` and read docs matching your task domain.
18
+ - Capture dated RFCs, runbooks, and evidence/progress notes in `docs/project/`.
19
+ - Capture adopted architecture decisions in `docs/adr/`.
20
+ - Confirm risks and dependencies.
21
+
22
+ ## 2) Implement
23
+
24
+ - Build in small commits.
25
+ - Keep command/tool behavior explicit.
26
+ - Update docs as behavior changes.
27
+
28
+ ## 3) Verify
29
+
30
+ - Run `npm run check`.
31
+ - Execute relevant extension tests.
32
+ - Validate prompt templates if changed.
33
+
34
+ ## 4) Release
35
+
36
+ - Run `npm run release:check` (or `npm run release:check:quick` for artifact-only CI mode).
37
+ - Confirm GitHub Actions settings allow marketplace actions and PR creation by workflows.
38
+ - Use release-please PR flow for versioning/changelog updates.
39
+ - For first-time npm packages, bootstrap once with token auth before switching fully to trusted publishing.
40
+ - Publish from GitHub release after publish workflow checks pass.
41
+ - Sync extension to live pi when needed.
42
+
43
+ ## 5) Maintain
44
+
45
+ - Monitor regressions and user feedback.
46
+ - Re-run validation after dependency/script changes.
47
+ - Keep `README.md` and `next_session_prompt.md` current.
@@ -0,0 +1,31 @@
1
+ ---
2
+ summary: "Compact project model with explicit project-purpose framing."
3
+ read_when:
4
+ - "Aligning project purpose, strategy, and delivery behavior."
5
+ system4d:
6
+ container: "Project-level concepts and boundaries for this repository."
7
+ compass: "Translate project purpose into executable outcomes."
8
+ engine: "Project purpose -> mission -> vision -> strategic objectives."
9
+ fog: "Project scope and priorities can drift without explicit review."
10
+ ---
11
+
12
+ # Project foundation model
13
+
14
+ ```mermaid
15
+ flowchart TD
16
+ ProjectPurpose("Project Purpose") -->|defines| ProjectMission("Project Mission")
17
+ ProjectMission -->|leads to| ProjectVision("Project Vision")
18
+ ProjectVision -->|is operationalized by| ProjectStrategicObjectives("Project Strategic Objectives")
19
+ ProjectPurpose -->|inspires| ProjectValues("Project Values")
20
+ ProjectValues -->|shape| ProjectEthics("Project Ethics")
21
+ ProjectValues -->|shape| ProjectCulture("Project Culture")
22
+ ProjectValues -->|are expressed in| ProjectCharter("Project Charter")
23
+ ProjectCharter -->|influences| ProjectEthics
24
+ ProjectEthics -->|guides behavior in| ProjectCulture
25
+ ProjectCulture -->|supports| ProjectStrategicObjectives
26
+ ```
27
+
28
+ ## Scope boundary
29
+
30
+ - **Organization purpose** lives at org level and is documented in [Organization operating model](../org/operating_model.md).
31
+ - **Project purpose** is repository-specific and can be narrower while staying aligned with organization strategy.
@@ -0,0 +1,17 @@
1
+ ---
2
+ summary: "Why this project matters and what outcomes are rewarded."
3
+ read_when:
4
+ - "Prioritizing roadmap work or evaluating tradeoffs."
5
+ system4d:
6
+ container: "Motivators and value model."
7
+ compass: "Favor changes that improve reliability and operator confidence."
8
+ engine: "Map work to measurable maintenance and delivery wins."
9
+ fog: "Incentives can drift if outcomes are not tracked."
10
+ ---
11
+
12
+ # Incentives
13
+
14
+ - Faster extension delivery.
15
+ - Lower regression risk.
16
+ - Clear docs for handoffs.
17
+ - Repeatable release and maintenance workflow.
@@ -0,0 +1,74 @@
1
+ ---
2
+ summary: "DesignMD Foundry Pi adapter integration contract."
3
+ read_when:
4
+ - "Before changing DesignMD Foundry extension tools or skill behavior."
5
+ system4d:
6
+ container: "Pi-facing adapter over DesignMD Foundry CLI workflows."
7
+ compass: "Expose verified design-contract operations without pretending optional external tools are installed."
8
+ engine: "Pi tool request -> DesignMD CLI command -> structured tool result."
9
+ fog: "Foundry path or optional external CLIs may be missing on an operator machine."
10
+ ---
11
+
12
+ # Integration contract
13
+
14
+ `pi-designmd-foundry` is a Pi adapter over the DesignMD Foundry CLI. It should not duplicate parser/linter/exporter logic.
15
+
16
+ ## Stable initial tool boundary
17
+
18
+ The extension exposes operations that are readiness-verified in DesignMD Foundry:
19
+
20
+ - `designmd_lint`
21
+ - `designmd_export`
22
+ - `designmd_agent_prompt`
23
+ - `designmd_oat_visual_snapshot`
24
+ - `designmd_openpencil_prompt`
25
+ - `designmd_openpencil_info`
26
+ - `designmd_openpencil_lint`
27
+ - `designmd_openpencil_export` for verified formats only: `svg`, `png`, `jpg`, `webp`, `fig`
28
+ - `designmd_import_penpot`
29
+ - `designmd_palette_from_text`
30
+ - `designmd_penpot_mcp_inspect` for read-only active-file bridge-board snapshots through official Penpot MCP
31
+ - `designmd_penpot_mcp_bridge` for plan-by-default / explicit-apply DesignMD canvas bridge board create/update operations through official Penpot MCP
32
+ - `designmd_penpot_mcp_export` for read-only SVG export of an existing DesignMD bridge board through official Penpot MCP
33
+ - `designmd_session_plan` for local `designmd.session-plan.v1` Watch Mode planning packets without canonical authority claims
34
+ - `designmd_session_variants` for local `designmd.session-variants.v1` proposal lanes without accepted-variant or canonical direction claims
35
+ - `designmd_session_handoff` for local `designmd.session-handoff.v1` prompts that bind one proposal lane into agent/operator guidance without canonical authority claims
36
+ - `designmd_session_guided_run` for local `designmd.guided-design-run.v1` orchestration packets that prepare plan, memory, variants, handoff, and report-back instructions without executing Pi or claiming canonical authority
37
+ - `designmd_session_closeout` for local `designmd.session-closeout.v1` Watch Mode evidence packets without canonical promotion claims
38
+ - `designmd_session_promotion_candidate` for local `designmd.promotion-candidate.v1` owner-review packets without promotion, publish, merge, or AK/society mutation claims
39
+ - `designmd_readiness`
40
+
41
+ ## Non-goals for the initial package
42
+
43
+ - No direct save of canonical `DESIGN.md`.
44
+ - No provider-backed LLM generation.
45
+ - No continuous Penpot webhook/plugin synchronization; the MCP bridge wrapper is limited to one explicit bounded board creation from `designmd.canvas-bridge.v1`, while the MCP export wrapper is limited to read-only SVG export of an existing bridge board.
46
+ - No OpenPencil JSX export wrapper until JSX behavior is fixture-verified.
47
+ - No claim that `open-pencil`/`openpencil` or `pigmnts` live CLIs exist unless DesignMD readiness reports them.
48
+
49
+ ## Runtime path resolution
50
+
51
+ The extension resolves the Foundry root in this order:
52
+
53
+ 1. Tool parameter `foundryRoot`.
54
+ 2. Environment variable `DESIGNMD_FOUNDRY_HOME`.
55
+ 3. Default local checkout: `~/ai-society/softwareco/owned/designmd-foundry`.
56
+
57
+ The CLI entrypoint uses `dist/cli.js` when present, otherwise source mode through Node type stripping.
58
+
59
+ ## Safety posture
60
+
61
+ Tools return command metadata and bounded stdout/stderr. Canonical writes are avoided; generated prompt, token, palette, and snapshot text is returned to the agent/operator for review. Artifact writes require an explicit output path, as with restricted OpenPencil export, Penpot MCP bridge-apply SVG proof output, and read-only Penpot MCP existing-board SVG export. The session plan, variants, handoff, closeout, and promotion-candidate tools can materialize only local Watch Mode artifacts/checks and explicitly do not create or promote AK/society authority. Variant lanes are proposals until accepted through the owning surface, and promotion candidates are owner-review packets only. Penpot MCP inspect and export are read-only. Penpot MCP mutation requires `apply: true` and a human-connected plugin; plan mode is the default. Update selectors such as `updateLatest` and `updateBoardId` may target only existing DesignMD bridge boards, are mutually exclusive, and remain non-mutating unless `apply: true` is set. Bridge plans/results include `designmd.penpot-mcp-transaction.v1` selector, target-resolution, postcondition, and rollback-classification evidence.
62
+
63
+ ## Optional Watch Mode reporting
64
+
65
+ When `DESIGNMD_SESSION_ENDPOINT` points at a Foundry session API root such as `http://127.0.0.1:8788/api/session`, every tool reports start/pass/fail activity to the current or newly created session. Output-producing tools also attach previewable artifacts when possible.
66
+
67
+ Reporting must stay optional and fail-open:
68
+
69
+ - no hidden dependency on a running Foundry server
70
+ - no tool failure just because session reporting failed
71
+ - no canonical authority claim for session/activity/artifact logs
72
+ - optional bearer token via `DESIGNMD_SESSION_TOKEN` or `DESIGNMD_API_TOKEN`
73
+
74
+ Use `DESIGNMD_SESSION_ID` only when the operator wants to bind reports to an explicit existing session.
@@ -0,0 +1,23 @@
1
+ ---
2
+ summary: "Key resources for building and maintaining the extension."
3
+ read_when:
4
+ - "Looking up references, docs, or operational artifacts."
5
+ system4d:
6
+ container: "Reference catalog for the project."
7
+ compass: "Centralize discovery paths for maintainers."
8
+ engine: "Link docs, scripts, and examples used in execution."
9
+ fog: "External links may become stale over time."
10
+ ---
11
+
12
+ # Resources
13
+
14
+ - [Extension entrypoint](../../extensions/designmd.ts)
15
+ - [Prompt templates](../../prompts)
16
+ - [Organization operating model](../org/operating_model.md)
17
+ - [Security policy](../../policy/security-policy.json)
18
+ - [Validation script](../../scripts/validate-structure.sh)
19
+ - [Trusted publishing runbook](../dev/trusted_publishing.md)
20
+ - [Biome config](../../biome.jsonc)
21
+ - [VS Code workspace settings](../../.vscode/settings.json)
22
+ - Tech-stack lane reference (pi extension TypeScript):
23
+ - `uv tool run --from ~/ai-society/core/engineering-core engineering-core show pi-ts --prefer-repo`