Add agent-agnostic AI skill structure with Docs/ reference guides#14
Open
amccall-mindera wants to merge 3 commits into
Open
Add agent-agnostic AI skill structure with Docs/ reference guides#14amccall-mindera wants to merge 3 commits into
amccall-mindera wants to merge 3 commits into
Conversation
- Create AGENTS.md at repo root as tool-agnostic source of truth - Create Docs/ with 7 reference guides extracted from copilot-instructions.md: Architecture.md, GraphQL.md, Localization.md, CodeStyle.md, Testing.md, Development.md, QuickReference.md - Add 7 standardised .ai/agents/ files: feature-orchestrator, feature-developer, graphql-specialist, localization-specialist, security-specialist, spec-writer, testing-specialist - Slim .github/copilot-instructions.md to a 5-line stub referencing AGENTS.md - Update all agent reference links to point to Docs/ files Agents are now named and structured consistently with Alfie-iOS and Alfie-Flutter. Agents located in .ai/agents/ for tool-agnostic compatibility (works with GitHub Copilot, Claude, Cursor, and any AGENTS.md-compatible tool). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
amccall-mindera
force-pushed
the
task/harmonise-ai-agent-skills
branch
from
ece27dd to
d98fb82
Compare
- feature-developer: use UseCaseResult.Success/Error (not Result.success/failure) to match project pattern; add model/ directory to module structure tree - testing-specialist: update mock stub to return UseCaseResult.Success to match UseCase return type - feature-orchestrator: fix phase dependency diagram — Phase 2 (security review) requires Phase 1 (spec) to complete first Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR restructures the repo’s AI-assistant guidance into an agent-agnostic format (root AGENTS.md + .ai/agents/*) and extracts the previously large Copilot instruction set into dedicated reference docs under Docs/, leaving .github/copilot-instructions.md as a lightweight pointer for compatibility.
Changes:
- Add
AGENTS.mdplus 7 standardized agent definition files under.ai/agents/. - Add 7 reference guides under
Docs/(Architecture, GraphQL, Localization, CodeStyle, Testing, Development, QuickReference). - Replace the existing
.github/copilot-instructions.mdwith a stub that points toAGENTS.md.
Reviewed changes
Copilot reviewed 16 out of 16 changed files in this pull request and generated 12 comments.
Show a summary per file
| File | Description |
|---|---|
| AGENTS.md | Root “source of truth” for agent usage, critical rules, and links to detailed guides. |
| .github/copilot-instructions.md | Stub Copilot instructions redirecting to AGENTS.md. |
| Docs/Architecture.md | Clean Architecture / MVVM / navigation reference guide extracted into Docs/. |
| Docs/CodeStyle.md | Compose + Hilt + Detekt + conventions reference guide extracted into Docs/. |
| Docs/Development.md | Development workflow + verification + CI/CD reference guide extracted into Docs/. |
| Docs/GraphQL.md | GraphQL/Apollo Kotlin integration guide extracted into Docs/. |
| Docs/Localization.md | Strings/plurals naming and usage guide extracted into Docs/. |
| Docs/QuickReference.md | “Things to avoid”, key directories/deps, review checklist, and context quick lookup. |
| Docs/Testing.md | JUnit5/MockK/Turbine patterns and coverage guidance extracted into Docs/. |
| .ai/agents/feature-orchestrator.agent.md | Defines the multi-phase orchestration workflow and delegation templates. |
| .ai/agents/feature-developer.agent.md | Implementation guidance for feature work (Compose + MVVM + Hilt). |
| .ai/agents/graphql-specialist.agent.md | Guidance for GraphQL operations, mappers, and service patterns. |
| .ai/agents/localization-specialist.agent.md | Guidance for string resources, naming conventions, and plurals. |
| .ai/agents/security-specialist.agent.md | Security review/audit checklist and remediation guidance. |
| .ai/agents/spec-writer.agent.md | Spec authoring workflow and required sections for feature specs. |
| .ai/agents/testing-specialist.agent.md | Test authoring workflow and patterns for ViewModels/use cases/mappers. |
Comments suppressed due to low confidence (2)
Docs/Testing.md:76
- This use case test snippet uses
assertThat(...).isInstanceOf(...), but the codebase’s tests predominantly usekotlin.testassertions (assertIs,assertEquals, etc.). Consider updating the example to match existing test conventions to avoid introducing an additional assertion library expectation.
fun `given repository returns brands when invoked then returns success`() = runTest {
val brands = listOf(Brand(id = "1", name = "Test Brand"))
coEvery { brandRepository.getBrands() } returns RepositoryResult.Success(brands)
val result = useCase()
assertThat(result).isInstanceOf(UseCaseResult.Success::class.java)
}
Docs/Architecture.md:113
- In this
whenexample,HomeUIState.Loadedis defined withhomeUI, but the snippet callsLoadedContent(state.data)(nodataproperty). This won’t compile as written and is inconsistent with the UI state definition just above. Update it to reference the correct property (e.g.state.homeUI) or bindwhen (val s = state)and uses.homeUI.
when (state) {
is HomeUIState.Loading -> LoadingContent()
is HomeUIState.Loaded -> LoadedContent(state.data)
is HomeUIState.Error -> ErrorContent()
}
Comment on lines
+36
to
+41
| fun `given success when loadData then emits Content`() = runTest { | ||
| coEvery { getFeatureUseCase() } returns Result.success(mockData) | ||
| viewModel.loadData() | ||
| viewModel.uiState.test { | ||
| assertThat(awaitItem()).isInstanceOf(FeatureUIState.Content::class.java) | ||
| } |
Comment on lines
+59
to
+67
| ```kotlin | ||
| internal class ProductService @Inject constructor( | ||
| private val apolloClient: ApolloClient | ||
| ) { | ||
| suspend fun getProduct(productId: String): Result<GetProductQuery.Product> = | ||
| apolloClient.query(GetProductQuery(productId)) | ||
| .execute() | ||
| .mapData { it.product } | ||
| } |
Comment on lines
+20
to
+35
| ## Example Pattern | ||
|
|
||
| **Query** (`network/src/main/graphql/GetProduct.graphql`): | ||
| ```graphql | ||
| query GetProduct($id: String!) { | ||
| product(id: $id) { ...ProductFields } | ||
| } | ||
| ``` | ||
|
|
||
| **Fragment** (`network/src/main/graphql/fragment/ProductFields.graphql`): | ||
| ```graphql | ||
| fragment ProductFields on Product { | ||
| id name brand | ||
| price { amount currency } | ||
| } | ||
| ``` |
Comment on lines
+33
to
+40
| ├── di/<Name>Module.kt # Hilt @Module | ||
| ├── presentation/ | ||
| │ ├── <Name>Screen.kt # @Destination Composable | ||
| │ ├── <Name>ViewModel.kt # @HiltViewModel + StateFlow | ||
| │ ├── <Name>UIFactory.kt # Maps domain model → UI model | ||
| │ └── model/ | ||
| │ ├── <Name>UI.kt # UI data model | ||
| │ └── <Name>UIState.kt # Sealed interface for states |
| - **Firebase**: Analytics, Crashlytics, Remote Config (BOM 32.7.3) | ||
| - **DataStore**: Preferences storage (v1.1.2) | ||
| - **Room**: Local database (if needed) | ||
| - **Timber**: Logging (latest) |
| #### Data Layer | ||
| - **Location**: `data/src/main/java/au/com/alfie/ecomm/data/` | ||
| - **Purpose**: Data sources, repositories implementation, DTOs, and data mapping | ||
| - **Pattern**: Repository pattern with protocol-based interfaces |
| ### Phase Dependencies | ||
|
|
||
| ``` | ||
| Phases 1-4 (parallel) --> Phase 5 --> Phase 6 --> Phase 7 --> Phase 8 |
| **Example Usage**: | ||
| ```kotlin | ||
| Text( | ||
| text = "Hello", |
| is UseCaseResult.Success -> _state.value = HomeUIState.Loaded( | ||
| uiFactory(result.data) | ||
| ) | ||
| is UseCaseResult.Error -> _state.value = HomeUIState.Error |
Comment on lines
+18
to
+36
| ## ViewModel Test Pattern | ||
|
|
||
| ```kotlin | ||
| @ExtendWith(MockKExtension::class) | ||
| class FeatureViewModelTest { | ||
| @MockK private lateinit var getFeatureUseCase: GetFeatureUseCase | ||
| private lateinit var viewModel: FeatureViewModel | ||
|
|
||
| @BeforeEach | ||
| fun setUp() { viewModel = FeatureViewModel(getFeatureUseCase) } | ||
|
|
||
| @Test | ||
| fun `given success when loadData then emits Content`() = runTest { | ||
| coEvery { getFeatureUseCase() } returns UseCaseResult.Success(mockData) | ||
| viewModel.loadData() | ||
| viewModel.uiState.test { | ||
| assertThat(awaitItem()).isInstanceOf(FeatureUIState.Content::class.java) | ||
| } | ||
| } |
- Docs/Development.md: fix phase dependency diagram (Phase 1 precedes 2-4) - Docs/Testing.md + testing-specialist.agent.md: use UseCaseResult.Success and assertIs instead of Result.success and assertThat().isInstanceOf() - Docs/GraphQL.md: fix service pattern to use GraphService + unwrap() matching repo convention - graphql-specialist.agent.md: fix query/fragment file paths to match repo structure - AGENTS.md: remove reference to non-existent Docs/Specs/Features path - security-specialist.agent.md: remove circular reference to QuickReference - Docs/Architecture.md: add missing message param to HomeUIState.Error example - Docs/QuickReference.md: pin Timber version to v5.0.1 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Introduces a fully tool-agnostic AI agent structure for the Android repo, consistent with Alfie-iOS and Alfie-Flutter.
Changes
New files
AGENTS.md— repo root source of truth (agents table, critical rules, pointers to Docs/).ai/agents/— 7 standardised agents:feature-orchestrator,feature-developer,graphql-specialist,localization-specialist,security-specialist,spec-writer,testing-specialistDocs/— 7 reference guides extracted from copilot-instructions.md:Architecture.md,GraphQL.md,Localization.mdCodeStyle.md,Testing.md,Development.md,QuickReference.mdModified
.github/copilot-instructions.md→ slimmed to 5-line stub pointing toAGENTS.mdWhy
Mirrors the structure established in Alfie-iOS (PR #62). All content is preserved — just reorganised so any AI tool (GitHub Copilot, Claude, Cursor, or any AGENTS.md-compatible tool) loads minimal context by default and reads detailed guides on-demand.