Imported from hdc8890/agentic-sdlc (AGENTS.md). Install upstream with npx skills add hdc8890/agentic-sdlc. Copyright stays with the author.

AGENTS.md

Project overview

This repository is the Agentic SDLC platform — the CLI and versioned contracts that engineering teams use to onboard their repositories to AI-driven workflows. It publishes tools that teams install and contracts that platform services (orchestration engine, memory service) consume.

The repo contains three things:

• contracts/v1/ — versioned JSON schemas that define the shared data model
• cli/ — the CLI tool teams use to onboard and validate configuration
• docs/ and examples/ — onboarding guide, architecture, and reference examples

If you are editing this repository, optimize for making it easy for a team to onboard their repo and for keeping contracts accurate and stable.

Core intent

Teams should be able to:

1. Run agentic init and agentic profile --generate in their repo
2. Review and merge the generated .agentic/ configuration
3. Trust that the orchestration engine and memory service will use that config correctly

Everything in this repo should serve that onboarding path, or document the contracts that the platform services implement.

Start here

Before making changes, read these files in order:

1. README.md
2. docs/onboarding/team-onboarding.md
3. docs/architecture/end-to-end-flow.md
4. docs/architecture/autonomy-levels.md
5. contracts/v1/domain.schema.json
6. contracts/v1/profile.schema.json
7. contracts/v1/policy.schema.json

Repository map

Root files

• README.md: human entrypoint — what this is, how teams adopt it.
• AGENTS.md: agent-oriented working context and instructions.

cli/

The agentic CLI. TypeScript/Node.js. Commands:

• agentic init — scaffold .agentic/ with starter profile and policy
• agentic profile --generate — auto-discover repo context and write profile
• agentic validate — validate .agentic/ against contracts/v1/ schemas
• agentic status — show current configuration and task state

Changes here must remain compatible with the contracts in contracts/v1/.

contracts/

Machine-readable schemas. These are normative — the source of truth for what .agentic/profile.json, .agentic/policy.json, and all platform entities must contain.

• contracts/v1/domain.schema.json — domain definition (repos, cross-repo deps, tribal knowledge)
• contracts/v1/profile.schema.json — repo profile (generated by CLI, consumed by orchestration)
• contracts/v1/policy.schema.json — team policy (autonomy level, review requirements)
• contracts/v1/task.schema.json — work item entering the orchestration engine
• contracts/v1/plan.schema.json — execution plan decomposed from a task
• contracts/v1/execution-unit.schema.json — single execution step
• contracts/v1/artifact.schema.json — output of an execution step
• contracts/v1/evaluation.schema.json — pass/fail evidence for an artifact
• contracts/v1/promotion.schema.json — promotion stage through PR/merge workflow
• contracts/v1/memory.schema.json — context stored and retrieved by the memory service

If you change a contract, update the CLI validation and the example in examples/onboarded-repo/.

docs/

• docs/onboarding/: step-by-step team adoption guide
• docs/architecture/: end-to-end flow, autonomy levels, layer model

examples/

• examples/onboarded-repo/: a real .agentic/ directory showing profile.json and policy.json after onboarding. Use this as a template and test fixture.

governance/

• governance/working-group.md: who owns what and how changes are reviewed

Working rules for agents

1. Contracts are canonical

contracts/v1/ is the source of truth. If there is tension between a contract and anything else in the repo, update the other thing to match the contract.

2. CLI must stay in sync with contracts

If you change a schema in contracts/v1/, check cli/src/commands/validate.ts loads and uses the updated schema. Check examples/onboarded-repo/ still conforms.

3. Examples must be valid

examples/onboarded-repo/.agentic/profile.json and policy.json must always pass agentic validate. Run this check after any contract or example change.

4. Onboarding guide is the human entrypoint

If teams would encounter a new concept or step during adoption, it belongs in docs/onboarding/team-onboarding.md. Architecture docs explain why; onboarding docs explain what to do.

5. Avoid framework lock-in

Do not introduce language that makes any specific orchestration framework, LLM provider, or runtime appear to be required.

6. Respect versioning

• breaking changes to contracts require a new major version (contracts/v2/)
• additive non-breaking changes are minor
• wording and example fixes are patch-level

Do not silently change the meaning of an existing v1 field.

Change guidance

When adding a new concept

• new team-facing config: add to contracts/v1/policy.schema.json and update CLI + example
• new platform entity: add to contracts/v1/ and update onboarding docs if teams need to know
• architecture explanation: docs/architecture/
• governance rule: governance/

When changing contracts

1. Update the schema in contracts/v1/
2. Update cli/src/commands/validate.ts if the validation logic changes
3. Update examples/onboarded-repo/ to conform to the new schema
4. Update docs/onboarding/team-onboarding.md if the change affects what teams configure

When changing the CLI

1. Verify the command still reads from contracts/v1/ for validation
2. Test with npm run dev -- <command> --dry-run in cli/
3. Update cli/README.md if command behavior changes

Validation

To validate the repo is consistent:

# Validate example .agentic/ against contracts
cd cli && npm install && npm run dev -- validate --dir ../examples/onboarded-repo

# Validate all JSON files parse correctly
node -e "
  const fs = require('fs');
  const { globSync } = require('glob');
  const files = globSync('**/*.json', { ignore: 'node_modules/**' });
  files.forEach(f => { try { JSON.parse(fs.readFileSync(f)); } catch(e) { console.error(f, e.message); } });
  console.log('All JSON valid');
"

Non-goals

Do not use this repo to:

• store per-team .agentic/ configurations (those live in each team's repo)
• prescribe a specific orchestration framework or LLM provider
• add speculative layer guidance that isn't grounded in the CLI or a working pilot
• weaken evaluation, traceability, or promotion semantics for convenience