finos / finos/architecture-as-code
Add Agent Skill to Facilitate Consistent CALM Control Requirement Creation
- Dominant language
- TypeScript
- Stars
- 399
- Forks
- 138
- Avg merge
- 2d 14h
- Merged PRs (30d)
- 37
Description
## Feature Proposal
### Target Project:
Add a tutorial to Practitioners section showing how to use an Agent skill to create a CALM Control Requirement JSON from a structured markdown document. [`examples/control-creation`](https://github.com/jimthompson5802/calm-practioner-skills/tree/main/examples/control-creation) is a proof-of-concept of the [`create-calm-control-req`](https://github.com/jimthompson5802/calm-practioner-skills/tree/main/.agents/skills/create-calm-control-req) skill.
### Description of Feature:
Add a new tutorial to the Practitioners section that teaches users how to author markdown-based control specifications and convert them into CALM control requirement JSON files, i.e., specifiction driven architecture. The tutorial should walk practitioners through drafting a control spec, generating a valid JSON Schema document, and using that generated requirement in a CALM architecture file.
Youtube video demonstrating skill use for the proposed tutorial: https://youtu.be/EC2h0wegy3U
### User Stories:
- As a non-technical CALM practitioner, I want a step-by-step tutorial for control requirement creation so that I can learn the workflow without reverse-engineering the example files.
- As a platform engineer, I want tutorial guidance for converting markdown control specs into CALM control requirement JSON so that I can reproduce the process consistently.
- As an architecture author, I want a tutorial that shows how generated requirement schemas fit into CALM validation flows so that I can confidently apply controls in architecture models.
### Current Limitations:
Current tutorials rely on ad hoc prompts with the CALM AI assistant. Those prompts already reduce manual effort compared with writing all control artifacts by hand, but the workflow can still produce inconsistent outcomes because results depend on how each user phrases or structures the request. Small prompt differences can lead to different control definitions, property interpretations, or output structure.
This proposed tutorial improves on that pattern by teaching a more structured workflow:
- Use the [`create-calm-control-req`](https://github.com/jimthompson5802/calm-practioner-skills/tree/main/.agents/skills/create-calm-control-req) skill instead of relying only on free-form prompt composition.
- Capture control intent in a markdown specification with explicit fields, property types, and constraints.
- Convert that structured input into CALM control requirement JSON in a repeatable way.
- Give practitioners a clearer path to more consistent control definitions across different users and sessions.
### Proposed Implementation:
- Technical design considerations
- Add a new tutorial entry in the Practitioners section focused on control requirement creation.
- Base the tutorial on the existing `examples/control-creation` materials so the narrative aligns with working repository assets.
- Organize the tutorial around the two modes of operation supported by `create-calm-control-req`:
- Template mode, which shows the markdown authoring template practitioners use to define a new control specification with structured fields, property types, and constraints
- Conversion mode, which takes a completed markdown specification and turns it into a CALM control requirement JSON artifact
- After describing those two modes, show how the generated requirement is used in pattern generation and validation workflows.
- Present the tutorial as guided documentation rather than as a deep explanation of the underlying skill implementation.
- Include references to the related example files so readers can follow the tutorial hands-on.
### Alternatives Considered:
- Leave the material as an example-only README under `examples/control-creation`.
- Rejected because referenced content is an personal GH repo, not under the control of the CALM project.
### Testing Strategy:
- Review the tutorial for technical accuracy against the existing example assets and skill behavior.
- Validate that every command and file reference in the tutorial works with the repository as checked in.
### Documentation Requirements:
- Add a new tutorial in the Practitioners section focused on control requirement creation.
- Cross-reference the tutorial to the existing `examples/control-creation` assets.
- Document the two skill modes: template authoring and conversion.
- Document the supported markdown property syntax and constraints in tutorial-friendly language.
- Document how generated requirements are referenced from architecture files and validated with `calm validate`.
- Update any relevant index or navigation pages so the tutorial is discoverable from the Practitioners area.
### Implementation Checklist:
- [ ] Design reviewed and approved
- [ ] Implementation completed
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Relevant workflows updated (if needed)
- [ ] Performance impact assessed
### Additional Context:
This proposal is derived from the existing example in [`examples/control-creation/README.md`](https://github.com/jimthompson5802/calm-practioner-skills/blob/main/examples/control-creation/README.md), which demonstrates:
- A markdown input spec for `CTRL-001` / `Sample Control`
- Generation of `sample-control-requirement.json`
- Use of the generated requirement from a CALM architecture `controls` block
- Validation through `calm validate -a -u url-mapping.json`
The main proposal-level inference is that this example should be promoted into a practitioner-facing tutorial in the repository’s Practitioners section rather than remaining outside of the CALM project. The exact placement and navigation model for that section should be validated during design review.
Contributor guide
Research direction
Start with examples/control-creation/README.md and the existing Practitioners section navigation. Build the tutorial around the create-calm-control-req template and conversion modes, including markdown syntax, generated JSON, architecture references, and the calm validate command. Done means the tutorial is discoverable, its references and commands match repository assets, and the workflow is technically accurate.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- json, markdown
- Domain
- cli, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 74/100