Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
2 changes: 1 addition & 1 deletion .husky/pre-commit
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
pnpm lint-staged
pnpm typecheck
pnpm lint:process --staged
pnpm architect:guard --staged
2 changes: 1 addition & 1 deletion .mcp.json
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"mcpServers": {
"delivery-process": {
"architect": {
"command": "npx",
"args": ["tsx", "src/cli/mcp-server.ts", "--watch"]
}
Expand Down
112 changes: 56 additions & 56 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,82 +4,82 @@ This file helps future Codex sessions ramp up quickly in this repository.

## Project Identity

- Package: `@libar-dev/delivery-process`
- Package: `@libar-dev/architect`
- Purpose: context engineering toolkit that extracts patterns from TypeScript + Gherkin into a queryable delivery state, generated docs, and workflow enforcement.
- Core principle: code/spec annotations are the source of truth; generated docs are projections.

## Where To Read First

1. Manual docs index: `/Users/darkomijic/dev-projects/delivery-process/docs/INDEX.md`
2. Config entry point: `/Users/darkomijic/dev-projects/delivery-process/delivery-process.config.ts`
3. Live generated area index: `/Users/darkomijic/dev-projects/delivery-process/docs-live/PRODUCT-AREAS.md`
1. Manual docs index: `/Users/darkomijic/dev-projects/architect/docs/INDEX.md`
2. Config entry point: `/Users/darkomijic/dev-projects/architect/architect.config.ts`
3. Live generated area index: `/Users/darkomijic/dev-projects/architect/docs-live/PRODUCT-AREAS.md`
4. Key generated area docs:
- `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/ANNOTATION.md`
- `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/CONFIGURATION.md`
- `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/CORE-TYPES.md`
- `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/DATA-API.md`
- `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/GENERATION.md`
- `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/PROCESS.md`
- `/Users/darkomijic/dev-projects/delivery-process/docs-live/product-areas/VALIDATION.md`
- `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/ANNOTATION.md`
- `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/CONFIGURATION.md`
- `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/CORE-TYPES.md`
- `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/DATA-API.md`
- `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/GENERATION.md`
- `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/PROCESS.md`
- `/Users/darkomijic/dev-projects/architect/docs-live/product-areas/VALIDATION.md`

## Onboarding Context (Tutorial WIP)

- External tutorial source: `/Users/darkomijic/dev-projects/delivery-process-tutorials/TUTORIAL-ARTICLE-v1.md`
- External tutorial source: `/Users/darkomijic/dev-projects/architect-tutorials/TUTORIAL-ARTICLE-v1.md`
- Tutorial goal: bootstrap from blank project to full docs/query flow (`11 patterns`, `26 generated files` in demo scenario).
- Treat tutorial outputs as illustrative; validate commands against current CLI behavior before codemods/docs changes.
- Important known alignment points from tutorial review:
- `process-api overview` includes the Data API helper section in output (not always shown in article snippets).
- Current `generate-docs --list-generators` output does not include `product-area-docs`.
- `generate-docs` accepts both repeated `-g` flags and comma-separated generator lists.
- `architect overview` includes the Data API helper section in output (not always shown in article snippets).
- Current `architect-generate --list-generators` output does not include `product-area-docs`.
- `architect-generate` accepts both repeated `-g` flags and comma-separated generator lists.
- Shape-derived entries can affect counts and `stubs` output (shape patterns appear as separate entries).
- `arch context` groups only patterns carrying explicit `@libar-docs-arch-context`.
- `arch context` groups only patterns carrying explicit `@architect-arch-context`.

## Consumer Repo Setup Conventions

When guiding users in external repos, pick command style based on config format:

- If the repo uses `delivery-process.config.js` (or no config), package binaries are fine:
- If the repo uses `architect.config.js` (or no config), package binaries are fine:

```bash
npx generate-docs --help
npx process-api --help
npx lint-patterns --help
npx lint-process --help
npx validate-patterns --help
npx architect-generate --help
npx architect --help
npx architect-lint-patterns --help
npx architect-guard --help
npx architect-validate --help
```

- If the repo uses `delivery-process.config.ts`, use `tsx`-based wrappers (or switch to `.js` config).
- If the repo uses `architect.config.ts`, use `tsx`-based wrappers (or switch to `.js` config).
- Reason: plain Node execution may fail to import `.ts` config files in some environments.

Use `delivery-process.config.ts` or `.js` as the main integration contract and keep scripts thin wrappers around package CLIs.
Use `architect.config.ts` or `.js` as the main integration contract and keep scripts thin wrappers around package CLIs.

## Architecture Snapshot

- Pipeline: `Config -> Scanner -> Extractor -> Transformer -> Codec`.
- Central read model: `MasterDataset` (consumed by docs generation, Data API, and validators).
- Preset in this repo config: `libar-generic` (`@libar-docs-*` tags).
- Preset in this repo config: `libar-generic` (`@architect-*` tags).
- Source ownership invariant:
- TypeScript owns runtime relationships (`uses`, `used-by`, category-like tags).
- Gherkin owns planning/process metadata (`depends-on`, quarter, team, phase, deliverables).

## Repository Map

- Source code: `/Users/darkomijic/dev-projects/delivery-process/src`
- Source code: `/Users/darkomijic/dev-projects/architect/src`
- Feature specs (roadmap/process/decisions/releases):
- `/Users/darkomijic/dev-projects/delivery-process/delivery-process/specs`
- `/Users/darkomijic/dev-projects/delivery-process/delivery-process/decisions`
- `/Users/darkomijic/dev-projects/delivery-process/delivery-process/releases`
- Design stubs (non-compiled on purpose): `/Users/darkomijic/dev-projects/delivery-process/delivery-process/stubs`
- `/Users/darkomijic/dev-projects/architect/architect/specs`
- `/Users/darkomijic/dev-projects/architect/architect/decisions`
- `/Users/darkomijic/dev-projects/architect/architect/releases`
- Design stubs (non-compiled on purpose): `/Users/darkomijic/dev-projects/architect/architect/stubs`
- Tests:
- Feature files: `/Users/darkomijic/dev-projects/delivery-process/tests/features`
- Step definitions: `/Users/darkomijic/dev-projects/delivery-process/tests/steps`
- Feature files: `/Users/darkomijic/dev-projects/architect/tests/features`
- Step definitions: `/Users/darkomijic/dev-projects/architect/tests/steps`

## Session Workflow (Project Convention)

Session types and expected outcomes:

1. Planning: create/update roadmap `.feature` spec (status typically `roadmap`).
2. Design: produce decision specs and/or stubs in `delivery-process/stubs/` (no implementation).
2. Design: produce decision specs and/or stubs in `architect/stubs/` (no implementation).
3. Implementation: transition `roadmap -> active -> completed` while implementing deliverables.

FSM/protection conventions:
Expand All @@ -93,20 +93,20 @@ FSM/protection conventions:
Use the CLI instead of broad file exploration whenever possible:

```bash
pnpm process:query -- overview
pnpm process:query -- scope-validate <PatternName> implement
pnpm process:query -- context <PatternName> --session implement
pnpm process:query -- dep-tree <PatternName>
pnpm process:query -- files <PatternName> --related
pnpm architect:query -- overview
pnpm architect:query -- scope-validate <PatternName> implement
pnpm architect:query -- context <PatternName> --session implement
pnpm architect:query -- dep-tree <PatternName>
pnpm architect:query -- files <PatternName> --related
```

Useful discovery commands:

```bash
pnpm process:query -- list --status roadmap --names-only
pnpm process:query -- arch blocking
pnpm process:query -- stubs --unresolved
pnpm process:query -- unannotated --path src
pnpm architect:query -- list --status roadmap --names-only
pnpm architect:query -- arch blocking
pnpm architect:query -- stubs --unresolved
pnpm architect:query -- unannotated --path src
```

## Build, Test, Validation Commands
Expand All @@ -123,9 +123,9 @@ pnpm test
Process/quality checks:

```bash
pnpm lint:steps
pnpm lint-patterns
pnpm lint:process
pnpm architect:lint-steps
pnpm architect:lint-patterns
pnpm architect:guard
pnpm validate:patterns
pnpm validate:dod
pnpm validate:all
Expand All @@ -147,7 +147,7 @@ pnpm docs:all

Rule: do not hand-edit generated artifacts when regeneration is the intended flow.

Current built-in generator list is discovered from CLI (`generate-docs --list-generators`).
Current built-in generator list is discovered from CLI (`architect-generate --list-generators`).
Do not assume undocumented generator names are available without checking.

## Testing Rules (Important)
Expand All @@ -169,11 +169,11 @@ Do not assume undocumented generator names are available without checking.

## Practical Start Checklist For New Sessions

1. Read `docs/INDEX.md` and `delivery-process.config.ts`.
2. Run `pnpm process:query -- overview`.
1. Read `docs/INDEX.md` and `architect.config.ts`.
2. Run `pnpm architect:query -- overview`.
3. If working on a specific pattern, run:
- `pnpm process:query -- scope-validate <PatternName> implement`
- `pnpm process:query -- context <PatternName> --session <design|implement>`
- `pnpm architect:query -- scope-validate <PatternName> implement`
- `pnpm architect:query -- context <PatternName> --session <design|implement>`
4. Make minimal source changes.
5. Run targeted tests + relevant lint/validation.
6. Regenerate docs if source annotations/specs/config changed.
Expand All @@ -184,14 +184,14 @@ There is currently no dedicated interactive onboarding command in this package.
If implementing one, design for existing-repo adoption first:

1. Command shape
- Add a new bin command (example: `delivery-process-init`) so users can run `npx delivery-process-init`.
- Add a new bin command (example: `architect-init`) so users can run `npx architect-init`.
2. Wizard responsibilities
- Detect package manager and module mode (`type: module`).
- Scaffold `delivery-process.config.ts` with chosen preset and discovered source globs.
- Offer optional npm scripts for `process-api`, docs generation, and validation commands.
- Optionally scaffold starter folders (`delivery-process/specs`, `delivery-process/stubs`) and sample spec/stub templates.
- Scaffold `architect.config.ts` with chosen preset and discovered source globs.
- Offer optional npm scripts for `architect`, docs generation, and validation commands.
- Optionally scaffold starter folders (`architect/specs`, `architect/stubs`) and sample spec/stub templates.
3. Safety requirements
- Dry-run mode and explicit overwrite confirmations.
- Never silently overwrite existing `delivery-process.config.ts` or user scripts.
- Never silently overwrite existing `architect.config.ts` or user scripts.
4. Success criteria
- User can run `process-api overview` and `generate-docs --list-generators` immediately after setup.
- User can run `architect overview` and `architect-generate --list-generators` immediately after setup.
4 changes: 2 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,5 +27,5 @@ First npm-published pre-release for monorepo validation.
- `@libar-dev/modular-claude-md` moved from dependencies to devDependencies
- Package size trimmed (removed self-referential docs from tarball)

[Unreleased]: https://github.com/libar-dev/delivery-process/compare/v1.0.0-pre.0...HEAD
[1.0.0-pre.0]: https://github.com/libar-dev/delivery-process/releases/tag/v1.0.0-pre.0
[Unreleased]: https://github.com/libar-dev/architect/compare/v1.0.0-pre.0...HEAD
[1.0.0-pre.0]: https://github.com/libar-dev/architect/releases/tag/v1.0.0-pre.0
Loading
Loading