101 lines
7.9 KiB
Markdown
101 lines
7.9 KiB
Markdown
# Design
|
|
|
|
## Context
|
|
|
|
See [proposal.md](proposal.md) for motivation. The current config selects `spec-driven` and contains commented examples only. README documents workflow and usage; `docs/architecture.md` documents runtime boundaries; the twelve specs are the reviewed behavioral baseline; RELEASE_NOTES records releases.
|
|
|
|
Read-only inspection covered those documents, `package.json`, `scripts/build.mjs`, `scripts/test.cjs` and the installed OpenSpec configuration parser. The installed CLI accepts `context` as a string, `rules` as artifact-keyed arrays of strings and `operations.apply/archive.guidance` as arrays of strings. No custom schema, store or dependency is necessary. Design is included to make the exact configuration and its cross-workflow effects reviewable before apply.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:** Make durable conventions available to future planning and implementation; separate shared context, artifact rules and advisory execution guidance; keep the candidate valid for the installed CLI.
|
|
|
|
**Non-Goals:** Turn config into a second README, freeze current endpoint URLs or module inventories, introduce executable policy enforcement, or make archive mean release. No main specification needs modification.
|
|
|
|
## Decisions
|
|
|
|
### Keep the standard schema and local root
|
|
|
|
Retain `schema: spec-driven`. Do not add a `store`, custom workflow or schema override: the existing local workflow already supports proposal/design/tasks and explicit spec skipping for tooling-only changes.
|
|
|
|
### Keep only stable constraints in shared context
|
|
|
|
Use a short context with documentation references, English output conventions, browser compatibility and the user's release expectations. Detailed APIs, role gates, storage keys, module layouts, test counts and URLs stay in the existing documents. This avoids a copied baseline drifting independently.
|
|
|
|
English artifacts and UI do not require English conversation: communication can continue in Portuguese. The Firefox-only XPI expectation applies when a release is requested; it does not drop Chromium/Edge support or authorize a release during ordinary work.
|
|
|
|
### Separate artifact guidance from operation guidance
|
|
|
|
`rules` describe the content of proposal, design, specs and tasks. `operations` hold apply/archive advice and do not override explicit choices, skill steps or CLI checks. Hardcoding developer-machine paths or adding redundant approval gates was considered and rejected.
|
|
|
|
### Proposed replacement for openspec/config.yaml
|
|
|
|
This block is the reviewed candidate, not an applied configuration. Replace the config with it only during apply.
|
|
|
|
```yaml
|
|
schema: spec-driven
|
|
|
|
context: |
|
|
Opportunities Extension supports Oracle Fusion workflows in Chromium/Edge and Firefox.
|
|
Write OpenSpec artifacts and extension-authored UI text in English; preserve service-provided names.
|
|
Use openspec/specs/ for behavioral contracts, docs/architecture.md for execution and storage
|
|
boundaries, README.md for setup and usage, and RELEASE_NOTES.md for release history.
|
|
Preserve both browser targets and the existing extension design system unless the change
|
|
explicitly proposes a compatibility or presentation change.
|
|
When a release is requested, include a valid Firefox XPI; XPI packaging is Firefox-only.
|
|
Keep the README main title as Opportunities Extension and release history in RELEASE_NOTES.md.
|
|
OpenSpec archival and product release are separate operations.
|
|
|
|
rules:
|
|
proposal:
|
|
- Identify affected existing capabilities and distinguish observed behavior from proposed changes.
|
|
- State scope, non-goals and compatibility impact; do not introduce product requirements for tooling-only changes.
|
|
design:
|
|
- Reference the relevant architecture contracts instead of duplicating their inventories.
|
|
- For affected integrations, describe request ordering, credentials, pagination, retries and stale-response handling.
|
|
- For affected persistence, describe ownership, identity scope, invalidation and migration or rollback needs.
|
|
- For UI changes, identify shared components and relevant loading, empty, failure and theme behavior.
|
|
specs:
|
|
- Describe observable behavior with testable scenarios; keep implementation steps and module wiring in design and tasks.
|
|
- Use synthetic identifiers and examples; never embed real tokens, cookies or personal contact data.
|
|
tasks:
|
|
- Tie each task to a concrete deliverable and include verification proportional to the affected behavior.
|
|
- For source changes, include relevant synthetic tests, regeneration of affected browser outputs and a build consistency check.
|
|
- Record installed-browser and live Oracle checks separately from synthetic tests, including checks not performed.
|
|
- Include version, release notes and Firefox XPI work only when release delivery is part of the requested scope.
|
|
|
|
operations:
|
|
apply:
|
|
guidance:
|
|
- Edit source modules and regenerate distributions through the build script; do not hand-edit generated bundles.
|
|
- Use synthetic data for automated checks and avoid incidental writes to live Oracle services during validation.
|
|
- Run focused checks for the change; use node scripts/test.cjs for integration verification of runtime changes and node scripts/build.mjs --check for generated-output consistency.
|
|
- Report what changed, verification results and material limitations without claiming unperformed browser or live-service validation.
|
|
archive:
|
|
guidance:
|
|
- Check documentation links when moving a change and preserve the distinction between archived evidence and current specifications.
|
|
- Summarize task completion, specification synchronization and the final archive location; do not treat archival as a product release.
|
|
```
|
|
|
|
### Validation approach
|
|
|
|
Parse the candidate as YAML and validate it with the installed OpenSpec configuration schema before apply. The context must be a nonempty UTF-8 string below 51,200 bytes; all artifact rule and operation guidance entries must be nonempty strings. Use only supported artifact and operation identifiers.
|
|
|
|
After apply, inspect `openspec context --json` and `openspec instructions proposal/design/tasks/apply/archive --change configure-project-context --json` as separate calls. Confirm context is delivered, artifact rules occur only on their matching artifact, and apply/archive advice is exposed as `operationGuidance`. For specs rules, inspect the parsed configuration rather than creating fictitious delta files or removing `skip_specs` just to probe a skipped artifact.
|
|
|
|
Run `openspec validate configure-project-context --strict`, `openspec validate --specs --strict` and `git diff --check`. A config-only change does not justify rebuilding distributions or running all runtime tests. Preserve baseline runtime verification as historical evidence, not a new test claim.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
- [Context becomes stale] -> Keep it short and reference existing authoritative files; omit current version, endpoint lists, absolute paths and test totals.
|
|
- [Guidance is mistaken for enforcement] -> Explain that config is prompt-level guidance; it does not guarantee tests, safe storage or API authorization.
|
|
- [New rules overconstrain unrelated work] -> Scope design rules to affected integrations/persistence/UI and verification to the change's impact.
|
|
- [A future CLI changes supported fields] -> Validate parsing and actual instruction delivery with the installed CLI when applying or upgrading.
|
|
- [Release expectations are misread as authorization] -> Keep release tasks conditional and explicitly separate archive from release.
|
|
|
|
## Migration Plan
|
|
|
|
During apply, replace only `openspec/config.yaml` with the candidate, verify configuration consumption and complete the tracked tasks. Existing specs, archived artifacts and runtime data need no migration. Future instruction reads receive the new guidance; existing artifacts are not rewritten automatically.
|
|
|
|
Rollback restores the prior config from the implementation diff without deleting changes or specs. No runtime deployment, data migration or browser reinstallation is required.
|