### Run documentation site locally Source: https://github.com/hieutran21198/software-engineering/blob/main/README.md Installs dependencies and starts the local documentation website using Node.js 24. ```sh cd website npm ci npm start ``` -------------------------------- ### Start a Change Request Source: https://github.com/hieutran21198/software-engineering/blob/main/src/archs/artifact-driven/06-guidelines/working-with-ai.md Use this prompt to initialize the ADD coordinator role with the necessary workspace and repository context. ```text Use the configured ADD coordinator role, backed by the skill at docs/artifact-driven/03-execution/skills/add-coordinator/SKILL.md. The knowledge workspace is . Implementation repositories are . I want . Interview me about material gaps before defining the change. Reuse established knowledge. Complete Requirement, Specification, and Plan with phase self-checks and commits on a dedicated branch, then stop and present the plan for my explicit approval. Do not implement yet. ``` -------------------------------- ### Clone, build, and list se-adopt Source: https://github.com/hieutran21198/software-engineering/blob/main/src/archs/artifact-driven/06-guidelines/adopting-from-git.md Clones the repository, builds the se-adopt command with Go 1.25 or later, and lists available architectures. Use an unused directory and replace the example URL and paths. ```sh git clone /path/to/software-engineering-source cd /path/to/software-engineering-source go build -o /tmp/se-adopt ./cmd/se-adopt /tmp/se-adopt --list ``` -------------------------------- ### Established Dependency DAG example (dag.yaml) Source: https://github.com/hieutran21198/software-engineering/blob/main/src/archs/artifact-driven/01-foundation/artifact-model.md Example YAML structure for the established dependency DAG stored at docs/artifacts/dag.yaml. Shows artifacts with paths and dependencies; authentication depends on tenant. Paths are relative to docs/artifacts/ and dependencies use the current established version. ```yaml artifacts: tenant: path: tenant depends_on: [] authentication: path: authentication depends_on: - tenant ``` -------------------------------- ### YAML references example Source: https://github.com/hieutran21198/software-engineering/blob/main/src/archs/artifact-driven/06-guidelines/writing-artifacts.md Shows the structure for detailed references in an artifact, naming the owning artifact, element path, and reason. ```yaml references: - artifact: tenant element: specifications/tenant-identity.md requires: tenant identifier format and lifecycle rules ``` -------------------------------- ### Preview and adopt with --arch artifact-driven Source: https://github.com/hieutran21198/software-engineering/blob/main/src/archs/artifact-driven/06-guidelines/adopting-from-git.md Runs a dry-run preview and then adopts the artifact-driven architecture into the consumer project. The default destination is docs/artifact-driven; use --output for another relative destination. Conflicting files stop adoption without overwriting. ```sh /tmp/se-adopt --arch artifact-driven --project /path/to/consumer --dry-run /tmp/se-adopt --arch artifact-driven --project /path/to/consumer ``` -------------------------------- ### Go development commands Source: https://github.com/hieutran21198/software-engineering/blob/main/README.md Runs tests, vet, and builds the se-adopt binary to /tmp/se-adopt from ./cmd/se-adopt. ```sh go test ./... go vet ./... go build -o /tmp/se-adopt ./cmd/se-adopt ``` -------------------------------- ### Build and run se-adopt to adopt ADD Source: https://github.com/hieutran21198/software-engineering/blob/main/README.md Build the se-adopt command with Go 1.25 or later and run it against a consumer workspace. The default output is docs/ inside the consumer workspace, currently docs/artifact-driven. Use --dry-run to preview or --output to choose a different relative destination. ```sh go build -o /tmp/se-adopt ./cmd/se-adopt /tmp/se-adopt --project /path/to/consumer ``` -------------------------------- ### Adopt with default settings Source: https://github.com/hieutran21198/software-engineering/blob/main/src/archs/artifact-driven/05-adoption/README.md Runs se-adopt from the consumer workspace with default settings, copying the selected bundle to docs/artifact-driven. ```sh /tmp/se-adopt ``` -------------------------------- ### List architectures and select ADD explicitly Source: https://github.com/hieutran21198/software-engineering/blob/main/src/archs/artifact-driven/05-adoption/README.md Lists available architectures with --list, or selects ADD explicitly with --arch. Unknown architecture names fail without writing. ```sh /tmp/se-adopt --list /tmp/se-adopt --arch artifact-driven --project /path/to/consumer ``` -------------------------------- ### Adopt with explicit project directory Source: https://github.com/hieutran21198/software-engineering/blob/main/src/archs/artifact-driven/05-adoption/README.md Runs se-adopt with the --project flag to specify the consumer directory explicitly. ```sh /tmp/se-adopt --project /path/to/consumer ``` -------------------------------- ### Build se-adopt binary Source: https://github.com/hieutran21198/software-engineering/blob/main/src/archs/artifact-driven/05-adoption/README.md Builds the se-adopt binary to /tmp/se-adopt using Go 1.25 or later. The binary embeds the bundle at build time; rebuild to include updated knowledge. Running the binary does not require the source repository or network access. ```sh go build -o /tmp/se-adopt ./cmd/se-adopt ``` -------------------------------- ### Preview changes and choose custom output destination Source: https://github.com/hieutran21198/software-engineering/blob/main/src/archs/artifact-driven/05-adoption/README.md Uses --dry-run to preview changes, or --output to choose a workspace-relative destination. The consumer workspace must already exist, output paths must remain inside it, and destination symlinks are rejected. ```sh /tmp/se-adopt --project /path/to/consumer --dry-run /tmp/se-adopt --project /path/to/consumer --output docs/add ``` -------------------------------- ### Project structure tree Source: https://github.com/hieutran21198/software-engineering/blob/main/README.md Shows the repository layout for cmd/, internal/, and src/ directories, including architecture resources, agent skills, and templates. ```text cmd/se-adopt/ # Adoption command internal/adopt/ # Workspace copy logic src/ ├── archs/ │ └── artifact-driven/ │ ├── README.md │ ├── 01-foundation/ │ ├── 02-methodology/ │ ├── 03-execution/ │ ├── 04-patterns/ │ ├── 05-adoption/ │ └── 06-guidelines/ └── utils/ ├── agents/ │ └── skills/ │ └── asd-ste-100/ │ ├── SKILL.md │ └── agents/ │ └── openai.yaml └── project/ └── assets/ └── templates/ └── README.md ``` -------------------------------- ### AI agent adoption request prompt Source: https://github.com/hieutran21198/software-engineering/blob/main/src/archs/artifact-driven/06-guidelines/adopting-from-git.md Prompt to ask an AI agent to adopt the bundle. Replace placeholders with actual values. Includes instructions for inspecting, building, previewing, adopting, configuring harness, and reporting conflicts. ```text Adopt Artifact-Driven Development into my knowledge workspace at using the Software Engineering repository at . [Use revision if required.] Inspect the workspace and its instructions first. Clone the source into a separate unused directory, inspect its instructions, and build se-adopt with Go 1.25 or later. Preview --arch artifact-driven with --dry-run, then adopt to docs/artifact-driven if no conflicts exist. Configure your own harness to use the bundled coordinator, PO, TL, and implementer skills. Use native team and skill capabilities; keep the canonical ADD bundle and its references intact. Add concise ADD guidance to the applicable existing AGENTS.md or CLAUDE.md, preserving unrelated instructions. Report any capability or instruction conflicts. The coordinator must interview me, complete Requirement, Specification, and Plan with self-checks and phase commits, then wait for my plan approval. A new plan or material change requires renewed approval. Independent implementation agents use separate worktrees. Dependent implementation waits for required established upstream versions. After validation, prepare proposed versions and linked PRs, then stop for team review and merge. Never commit directly to protected branches. Preserve existing edits and stop on conflicts. Check that the adopted overview, skills, patterns, and guideline links resolve and that your harness can load the configured roles. Report the source revision, destination, and setup changes. Adoption does not authorize starting a domain change, implementing it, committing setup, pushing, or merging. ``` -------------------------------- ### Gherkin scenario for tenant-scoped login Source: https://github.com/hieutran21198/software-engineering/blob/main/src/archs/artifact-driven/04-patterns/behavior-driven-development.md Illustrative Given/When/Then scenario showing a user with no active membership is denied access to a tenant. Assumes the PO has confirmed the membership rule. ```gherkin Feature: Tenant-scoped login Scenario: A user has no active membership Given a user has valid credentials And the user has no active membership in the requested tenant When the user attempts to sign in to that tenant Then access to that tenant is denied ``` -------------------------------- ### dependencies.yaml: Proposed edge updates for authentication artifact Source: https://github.com/hieutran21198/software-engineering/blob/main/src/archs/artifact-driven/01-foundation/artifact-model.md Stores proposed edge updates in the dependent artifact's active change. The 'add' list specifies new dependencies (here, 'tenant') and 'remove' lists dependencies to remove. This file is used during planning to combine with the established graph. ```yaml artifact: authentication add: - tenant remove: [] ```