Skip to content
v1.6.0MIT

Full SDLC activities, artifact and activity systems, requirements and quality-attribute design, delivery, operations, platform/AWS, security and governance assurance.

SDLC plugin: activities, artifacts and evidence

The sdlc plugin is the default bundle for the full software development lifecycle. It carries development, delivery, operations and assurance activities, project foundations, contribution flow, verification methods and two core models:

  • the activity model, which routes the work;
  • the artifact model, which gives every durable output a shared shape.

Artifact system in one sentence: every durable engineering output is an artifact with a type, plane, home, authority, maturity, relations and evidence; the artifact system is the shared model that keeps those artifacts sufficient, navigable and consistent.

Activity system in one sentence: every requested engagement is an activity with an intent, entry conditions, output, stopping point, authority, artifacts and evidence; the activity system is the router that keeps work scoped and composable.

These are the two core models. The activity system decides what work is being done and where it stops. The artifact system decides what durable outputs are produced, where they live, and what evidence they carry.

The conceptual model

The rest of the plugin is composed from a small set of concepts. Two are core models; the others are composition layers or dimensions.

ConceptQuestion it answersStatus
ArtifactWhat durable output is produced?Core model — artifact-system
ActivityWhat work is requested, and where does it stop?Core model — activity-system
MethodWhat reusable expertise deepens the work?Supporting capability — TDD, code review, requirements engineering, guide-* artifact guides
WorkflowWhat ordered sequence carries the work out?Composition pattern — e.g. the contribution workflow
RoleWho participates?Dimension — product, implementer, reviewer, operator
PhaseWhere in the SDLC lifecycle?Dimension — planning, requirements, design, implementation, verification, release, maintenance
Software typeWhat kind of component is being designed?Dimension — frontend, backend, AI, library/CLI; a component property, not skill metadata
HomeWhere does the artifact live?Dimension — engineering workspace, repo, tracker, provider, operations repo
EvidenceWhat supports the claim?Quality and assurance — quality bar, artifact assurance

Artifact and activity are the core. Method, workflow, role, phase, home and evidence are not competing top-level systems; they are layers or dimensions applied to those two models.

Workflow is a composition, not a third core model

A workflow is an ordered execution path inside or around an activity. It is not a new core object.

  • An activity is “implement the agreed change” or “verify this behavior.”
  • A workflow is “create a worktree → verify → commit → push → open or update the PR.”
  • A method is “how to review a diff” or “how to design a test.”

git-contributions is the clearest workflow-shaped method in the current plugin. It sequences contribution mechanics and produces or updates artifacts, but it does not own the PR artifact. The PR contract owns the reviewer-facing content; the workflow owns the mechanics.

The same distinction applies elsewhere: release is an activity, while readiness → promotion → verification → observation is a workflow; system-documentation is an activity-shaped method, while trace → evidence → view is its internal sequence.

If the same ordered sequence is reused across several activities, it can become a formal reference under activity-system/references/workflows/. Until then, “workflow” remains a useful label for a method’s internal sequence, not a separate system.

Skill metadata

Skills carry a small classification layer:

  • kind: system, activity, method, workflow or reference.
  • pack: sdlc, technical, craft or product.
  • domain: the owning lifecycle/capability area, such as development, delivery, operations, security, governance, frontend, backend, database, AI, documentation or visualization.
  • phase: planning, requirements, design, implementation, verification, release, maintenance or cross-phase.
  • origin: local or upstream.
  • scope, invocation and role: generic/stack-specific, user/agent/both and task/support labels.

The full artifact and activity catalogs remain the source of truth for artifact types, homes and evidence. Skill metadata is for discovery and maintenance, not execution routing. python scripts/skill_inventory.py prints the generated maintainer matrix: Skill, Pack, Domain, Kind, Phase, Origin, Scope, Invocation, Role and Plugin.

Software types are a component property

A project is made of components. Each component has a software type: frontend, backend, ai or library-cli. A change declares which types it touches and which are explicitly not affected.

The type selects the typical artifacts and evidence a design record needs. It is not a project-wide label, a skill metadata value or a reason to create one contract per type. A normal web application is a frontend component plus a backend component, not a "full-stack" type.

Platform and domain variations are constraints, not additional types:

VariationHandled as
Browser extensionFrontend + browser-extension-development constraints
REST APIBackend + contract/versioning constraints
Multi-tenant SaaSBackend/frontend + saas-development constraints
AI stack (ADK, LangChain)AI + provider/framework constraints
Database, offline-first, real-time, regulated dataComponent/project constraints

Read software types for selection, the anti-rigidity rules and the four type references.

Why the plugin is organized this way

The system separates artifact type and lifecycle, subject matter, writing craft and storage placement. They are orthogonal dimensions: combining them into one universal document method creates overlap. The artifact and activity systems own the shared model, while domain methods and writing craft specialize it.

The correction is to separate the dimensions:

  • Functional requirements are per artifact type: purpose, authority, lifecycle, status, required content, evidence and link obligations. They belong in the artifact contract.
  • Non-functional requirements are mostly cross-cutting: reader fit, explanation, structure, examples, style, navigation, links and render fidelity. They belong in a shared quality bar plus a writing-craft skill, not inside every contract.

Writing is not a “dimension inside each artifact.” It is the craft that produces the non-functional outcome. The artifact contract requires the outcome; the craft skill teaches how to achieve it.

The artifact model

An engineering artifact is a durable, addressable unit of engineering intent, knowledge, implementation or evidence that a reader can inspect and that has an authority, a lifecycle and a home.

FieldQuestion
IdentityWhat stable name or key identifies it?
TypeECR, PRD, ADR, issue, PR, architecture set, runbook, code module, test suite, release note, README or guide?
PlaneWhat is its primary role: intent, coordination, system knowledge, implementation, delivery or entry?
AuthorityIs it the source of truth for its concern?
HomeEngineering workspace, application repository, tracker, git provider or operations repository?
MaturityProposed, accepted, implemented, verified, released, superseded, active or retired?
ReaderProduct, implementer, reviewer, operator or new contributor?
ContractWhat must it contain?
RelationsDerives from, informs, decides, proposes, implements, verifies, documents, projects, supersedes, releases or operates?
EvidenceSource revision, command, test, CI run or runtime observation?
FreshnessWhen must it be updated or retired?
AccessPublic, private, audience-specific?

Software type is not an artifact field. An artifact describes a component or change; the component's software type selects the typical artifacts and evidence the artifact needs.

Read the full model in artifact model. Choose a type in the artifact catalog. Resolve its location with artifact homes.

The activity model

An activity is a requested engagement. It has the same kind of explicit shape as an artifact:

FieldQuestion
IdentityWhat activity is this?
IntentWhat outcome does the requester want?
Entry conditionsWhat must be known or decided before it starts?
OutputWhat does the requester have afterward?
Stopping pointWhere does this activity deliberately stop?
AuthorityWhat may it read, write, publish, merge or deploy?
ArtifactsWhich artifact types does it produce or consume?
Supporting methodsWhich disciplines may deepen the work?
EvidenceWhat shows the activity is complete?
TransitionsWhat can follow, and what must not be silently invoked?
InvocationUser-facing, agent-support or explicit-only?

Read activity system for the routing model. The activity catalog lists the activities, default results and stopping points. Transitions explains handoffs and re-entry. Engagement state explains focus, parallel threads and reopens. Composition explains how supporting methods are selected. Authority explains action scope and unattended work. Project fit keeps the work proportionate.

The plane model

A plane describes the artifact's primary role. It is not a storage bucket.

PlaneRoleExample artifactsTypical readers
IntentWhy and what to pursuePRD, roadmap, product decision recordProduct, leadership
CoordinationTrack a change, its decisions and evidenceECR, research report, RFC, issue, PRChange participants, reviewers
System knowledgeExplain the implemented systemArchitecture set, contracts, API reference, ADRs, runbooks, SLOsContributors, operators
ImplementationBuild and verify the systemCode, tests, migrations, configurationEngineers, reviewers
Delivery and operationsRelease and operateRelease notes, changelog, deployment records, incidents, postmortemsOperators, maintainers
Entry and knowledgeHelp someone start or learnREADME, guides, tutorials, glossary, contributor guideNew users, contributors

Planes are a navigation view, not an exclusive taxonomy. An artifact has a primary plane and may have secondary relations:

  • The ECR is coordination-first but links intent, implementation, system knowledge and delivery.
  • An ADR is system-knowledge-first but records a change decision.
  • A PR is coordination-first but is also delivery evidence.
  • A test suite is implementation-first but is also verification evidence.
  • A README is entry-first but also describes the system.

Homes are attributes

A home is where the authoritative copy lives. It is separate from the plane. An architecture view is system knowledge and usually lives in the application repository under docs/architecture/; a runbook is also system knowledge but may live in ops/<application>/runbooks/. An ECR lives in the engineering workspace.

The same artifact type can move homes without changing its contract. The model therefore separates:

  • Plane — role.
  • Home — location.
  • Authority — truth for a concern.
  • Maturity — what claim the artifact may make.

Read artifact homes for default homes, alternates, the resolution method and the repository map template.

The repository artifact home map

Every project should record where its durable artifacts live. A short pointer belongs in AGENTS.md; the full map belongs in docs/README.md or docs/artifact-homes.md.

The map records, for each artifact type:

  • the authoritative home;
  • the owner;
  • the update trigger;
  • the access boundary.

The map is project-specific. The resolution method is generic and lives in the artifact system. setup establishes or verifies the map; project-conventions maintains the repository placement method; develop, implementation and release read or update it. If the map is missing, treat that as a project-foundation gap rather than choosing an arbitrary docs/ path.

The artifact graph

Relations use a small, stable vocabulary:

RelationMeaning
derives_fromTakes intent or constraints from another artifact
informsProvides evidence or context to another
decidesRecords an accepted choice that constrains another
proposesOffers a design that another may accept or reject
implementsRealizes an accepted change
verifiesObserves or proves accepted behavior
documentsExplains the implemented system or its operation
projectsPresents a view of another authority for an audience
supersedesReplaces an earlier artifact or decision
releasesRecords delivery to a target
operatesGoverns running-system behavior

The graph is the real structure. Planes are a view over it.

PRD ──informs──▶ ECR ──proposes──▶ RFC
                   │                 │
                   ├──decides──────▶ ADR
                   ├──coordinates──▶ issue
                   ├──implements───▶ code / tests / migration
                   ├──verifies─────▶ CI / runtime evidence
                   ├──projects─────▶ PR
                   ├──documents────▶ architecture set / runbook
                   └──releases─────▶ release note

The ECR is the coordination spine, but every node is an artifact with its own authority and evidence. Code and tests are not appendices to the ECR; repo documents are not copies of it.

Functional and non-functional requirements

LayerExamplesOwner
Functional artifact requirementsPurpose, authority, required sections, status, evidence, relations, update rulesArtifact contract + domain method
Shared non-functional floorSelf-contained context, readable structure, resolvable links, render fidelity, one authorityArtifact quality bar
Writing craftReader modeling, explanation, examples, precision, tone, navigationTechnical writing craft
Artifact-specific non-functional parametersADR conciseness and immutability; runbook scannability under pressure; PRD persuasive but evidence-based; architecture-view precisionContract parameters + domain method

The contract states the outcome; the craft skill teaches how to achieve it. This is why writing is not a section inside every contract and not a separate artifact system.

Skills organization

artifact-system

The shared artifact model. It owns:

  • the artifact model, planes and relations;
  • the catalog of artifact types and default homes;
  • the four software types and the evidence each design needs;
  • handoff content for the next phase, assembled from linked artifacts;
  • home resolution and the repository map method;
  • the quality bar;
  • cross-artifact assurance;
  • the artifact contracts, including the design proposal.

Start at artifact system. Use the catalog to choose a type, the homes reference to resolve a location, the relevant contract for content, and the quality bar before handoff.

activity-system

The shared routing model. It owns:

  • the activity catalog, default results and stopping points;
  • transitions, re-entry and parallel threads;
  • engagement state: focus, active threads, parked asides and reopens;
  • composition and fallback;
  • action authority and unattended execution;
  • project fit and proportionality;
  • the user-facing help mode.

Start at activity system. Use the catalog to choose an activity, transitions for handoffs and re-entry, engagement state for interleaved work, composition for supporting methods, authority for action scope and project fit for proportionality.

design

design is the design activity. It frames the decision and affected software types, generates three or more materially different options for consequential choices, requires type-appropriate linked artifacts, decides the seam when several types meet, validates the direction when uncertainty is material and hands off without implementing.

Use the design activity, the option set, design validation, design review, software types and the design proposal contract.

Artifact guides

Every artifact type has a contract and, where the craft is distinct, a guide. The contract owns lifecycle, authority, maturity, evidence and handoff; the guide owns structure, conventions, examples, common failures and review. The full one-to-one pairing is the guide registry.

  • Document guides: guide-prd, guide-rfc, guide-adr, guide-ecr, guide-design-proposal, guide-architecture-set, guide-issue, guide-pr, guide-research-report, guide-release-note, guide-readme.
  • Operational guides: guide-runbook, guide-incident-record, guide-postmortem, guide-assurance-assessment.
  • Artifact/view guides: guide-design-spec, guide-c4-view, guide-sequence-view, guide-state-machine, guide-compatibility-matrix.

Each guide can be used inside an activity or requested directly. The guides are self-contained writing methods; they do not link into the artifact system.

Coordination storage

The storage mechanics for coordination artifacts now live inside artifact-system under references/storage/: discovery, identity, persistence, revisions, provider limits and access. The reference owns how to publish an ECR or research report; the artifact system owns what it contains and where it belongs.

project-conventions and setup

project-conventions owns repository foundations, including the artifact home map. setup establishes or verifies the map and records a portable pointer. This is how the phases become aware of placement: setup creates the map, implementation reads it, release updates the mapped records.

system-documentation and system-design

system-documentation discovers and documents the current system: entry points, runtime relations, data journeys, deployment topology and the architecture document set. It records each component's software type and constraints in the inventory. system-design owns proposed architecture and consequential choices; it uses the option set and records the decision in the design proposal. The artifact system owns the architecture-set contract, status, evidence and home.

test

test is the verification activity. It selects and runs checks, observes real behavior, reviews completion evidence and reports coverage gaps. It does not merge, deploy or publish.

Contribution workflow

git-contributions is a workflow-shaped support method. It owns the ordered mechanics: establish the objective worktree, verify and commit, push, and create or update the pull request. It does not own the PR artifact’s content; the PR contract owns the reviewer-facing why, what, design impact, validation at the current head, risk, links and visibility. The workflow produces the artifact; the contract defines it.

Delivery and operations

release owns the delivery activity; the ci-cd-pipelines method owns provider-neutral CI/CD stage, artifact-promotion, gate and recovery design, with tooling-conventions for the selected provider implementation. production-readiness owns the scoped question of whether a service is ready to be depended on, using assurance evidence without authorizing a release. application-configuration owns configuration precedence, typed validation, secret separation and reload behavior. Operations activities cover incident response, observability, runbook, data recovery, security maintenance, capacity and cost, operations reviews and postmortems. system-design owns quality-attribute design tactics, including reliability and disaster recovery, through its quality-attribute references; observability implements the signals.

Security and governance

security-and-privacy-design, security-auth-development and compliance-readiness are assurance methods. They attach to the activity that owns the decision and evidence; they do not form a separate phase. Security decisions live in ADR/ECR and verification evidence. Compliance readiness uses the assurance assessment contract.

Domain methods

Requirements engineering, system design, system documentation, security, operations, database, frontend, backend and AI skills own their subject methods. The artifact contracts link to them by capability; the activity system composes them without duplicating their content.

Writing craft

Technical writing lives in the documentation plugin. It owns reader fit, explanation, structure, examples, precision, navigation and presentation. It takes audience, purpose and required sections from the artifact contract. It does not own placement, status, evidence or content contracts.

Explicit upstream workflows

grill-me, grill-with-docs, grilling, to-spec, to-questionnaire, retro, handoff and improve-codebase-architecture remain explicit workflows. Their names, bodies and native controls are preserved. The activity catalog lists them separately from default activities.

Composability and reusability rules

  1. One owner per rule. Link navigation lives in the quality bar, not in every contract. C4 coverage lives in system documentation, not in the ECR contract. Prose craft lives in technical writing, not in the issue template.
  2. Contracts are thin routers, not methods. A contract says what the artifact must contain and which domain/craft capability to use. It does not re-teach architecture, product strategy or prose.
  3. Progressive disclosure. The system skill carries the model and reading path. Contracts, activity references and domain skills load only when relevant.
  4. Capability-based composition. Use available subject and craft expertise by description, not a hardcoded dependency graph.
  5. Stable vocabulary. Artifact, type, plane, home, authority, maturity, contract, relation, evidence, activity, stopping point, transition, method, workflow, role and phase mean the same thing in every skill.
  6. Separate what / how / where / whether. What = artifact contract. How = domain method and craft. Where = homes and repository map. Whether = quality bar and assurance.
  7. No universal template. A PRD, ADR, runbook and ECR have different functional requirements. The shared model is fields and relations, not identical sections.
  8. Evaluate composition, not just individual skills. A change should be judged by whether the PRD, ECR, RFC/ADR, issue, PR, code, tests, architecture view and runbook agree on scope, status, revision and evidence.

Reading paths

For a change

  1. Choose the activity in activity system.
  2. Use the artifact catalog to select the ECR and any linked types.
  3. Resolve the ECR home with artifact homes and coordination storage.
  4. Read the ECR contract.
  5. Apply the quality bar and assurance.

For a design decision

  1. Read software types and state the affected components and types, or mark them assumed.
  2. Use the option set for a consequential choice: three or more materially different directions.
  3. Represent each option for its type and decide the seam when several types meet.
  4. Record the result in the design proposal contract, as ECR §4, an RFC or a linked design record.
  5. Validate with design validation when uncertainty is material, and hand off through design review.

For a repository document

  1. Read the repository artifact home map.
  2. Choose the type: architecture set, ADR, runbook, README, guide, release note or API reference.
  3. Read its contract.
  4. Use the domain method for the subject and technical writing for craft.
  5. Apply the quality bar and update the map if the type, home or owner changed.

For a work product

  1. Link it to the ECR, issue, requirement or ADR it implements or verifies.
  2. Use the language/framework/test guidance for implementation quality.
  3. Record the checked revision and evidence.
  4. Reconcile affected architecture views, contracts, runbooks and API reference.
  5. Do not turn the work product into a second ECR.

Boundaries

This is guidance, not an executable gate. Package checks establish structure, links and packaging; they do not establish agent adherence, application behavior or deployment. The activity and artifact systems do not grant permission to create issues, publish documents, merge, deploy or access providers beyond the requested scope.

A compact artifact can pass; a long artifact can fail. The test is whether the reader can decide and act, not whether every heading exists.

Migration

Use activity-system for routing, test for verification and the repository artifact home map for placement. system-documentation explains the current system. For old names and removal notes, see the migration guide.

MCP connections

The plugin declares optional hosted endpoints for common project-management systems in mcp.json:

SystemEndpointAuthentication
Atlassian (Jira, Confluence, Bitbucket)https://mcp.atlassian.com/v2/mcpOAuth 2.1
GitHub, including Projectshttps://api.githubcopilot.com/mcp/OAuth or a personal access token
Linearhttps://mcp.linear.app/mcpOAuth 2.1
Planehttps://mcp.plane.so/http/mcpOAuth

Each server acts as the signed-in user and inherits that account's permissions. The declaration does not establish authenticated access or write authority, and declaring all four does not connect them. Connect only when the requested work needs that system; verify the intended workspace, project or repository before creating or changing work items, and use the narrowest account and scopes the task allows.

Linear also exposes a read-only endpoint at https://mcp.linear.app/mcp/readonly. GitHub exposes read-only variants such as https://api.githubcopilot.com/mcp/readonly; the declared X-MCP-Toolsets: default,projects header adds Projects tools to its default set.

Sources

  • The retired upstream implement entry point is preserved as a reference: mattpocock/skills implement (MIT). It is not an acquired skill and its body is not packaged.

References

NeedSource
Artifact model and planesartifact model
Type selection and contractsartifact catalog
Software types and required evidencesoftware types
Design options, validation and reviewdesign activity, option set, design validation, design review
Design proposal contentdesign proposal contract
What the next phase needshandoff
Home resolution and repository mapartifact homes
Readiness, consistency and convergenceartifact assurance
Activity selection and stopping pointsactivity system
Focus, parallel threads and reopensengagement state
Composition and fallbackactivity composition
Coordination storagecoordination storage
Repository foundationsproject conventions
User-facing guideengineering artifacts and workspaces
Migration from old namesmigration guide